설치·실행·업데이트·복구

이 문서는 소스가 선언한 운영 경로를 정리한다. 명령·컨테이너·DB migration·update·archive를 실제 실행하지 않았으므로 “실행 가능 확인”이 아니라 “코드/manifest 확인”이다.

정상 운영 명령·파일 index

install.sh, update.sh, dev.sh는 $@를 parse하지 않는다. 정의된 option이 없고 전달한 argument는 효과가 없다. build.sh와 reset-password.sh만 독립적인 script option parser를 갖는다.

프로세스 시작 순서

cmd/artex/main.go의 run은 다음 순서다. main 근거

1. -addr 기본 :8787, -data 기본 <BaseDir>/data, -proxy 기본 127.0.0.1:8788을 파싱한다.
2. log capture를 시작한다.
3. DB/port를 열기 전에 self-update bootstrap을 수행하고 교체/rollback이면 exit code 75로 supervisor 재시작을 요청한다.
4. NewManager가 필수 PostgreSQL, 선택적 traffic proxy, engine stores를 연다.
5. server가 skill/data/base 경로와 함께 API/UI를 구성한다.
6. HTTP server를 시작하고 signal 또는 update restart를 기다린다.
7. 종료 시 agent abort cause를 전달하고 HTTP에 5초 graceful shutdown window를 준다.

소스 파일 상단의 “dual SQLite graph stores” 주석은 현재 PostgreSQL 기반 업무 상태와 맞지 않는 오래된 설명이다. 실제 constructor와 schema를 우선한다.

설정 우선순위

전체 key와 저장/재조립 경계는 설정 계약이 소유한다.

PostgreSQL이 열리지 않으면 server가 시작하지 않는다. traffic proxy 초기화 실패는 로그를 남기고 capture disabled 상태로 계속할 수 있다. config 근거 manager 근거

Grep bootstrap의 network·filesystem 효과

Norma Grep는 read-only tool로 노출되지만 기본 상태의 첫 호출은 PATH에 rg가 없을 때 npm install -g @vscode/ripgrep를 실행할 수 있다. Registry network access와 npm global prefix 쓰기 권한을 ARTEX process에 요구하며, package version은 pin하지 않는다. 이 command는 ARTEX tool/intercept trace에 별도 호출로 남지 않는다. 실패 원인은 숨기고 pure-Go 검색으로 계속하므로 정상 검색 결과도 설치 성공·실패·미시도를 구분하지 않는다. 도구 효과 resolver 근거

Container/read-only host에서는 global prefix가 쓰기 불가여도 application startup은 실패하지 않는다. 설치 시도는 startup이 아니라 process의 첫 Grep 호출에서 발생하고 process마다 sync.Once 상태가 초기화된다. 재현성과 egress 통제가 필요하면 image/package build 단계에서 승인한 rg를 고정하거나 위 suppression env를 service definition에 명시해야 한다.

상태 경로

Schema 적용

DB open은 PostgreSQL advisory lock을 잡고 embedded schema.sql을 매 시작 실행한다. 고정 source revision의 core 분모는 49 table·520 final column·97 index·4 function·22 trigger이며, DDL은 IF NOT EXISTS, ALTER, conditional DO, backfill을 섞은 idempotent 방식이다. deadlock code 40P01에는 짧은 retry가 있다. 이후 built-in agents/tools/rules/visibility를 seed한다. DB 근거 DB 객체 참조

단일 migration ledger가 없으므로 “현재 binary가 기대하는 schema”는 해당 revision의 schema.sql과 코드의 별도 Ensure*Table 함수 조합이다. 실제 DB가 어느 DDL까지 성공했는지 확인하는 version row는 없다. core schema/seed 오류는 대체로 fatal이지만 18-column llm_records와 13-column llm_usage ensure 실패는 manager가 로그 후 진행한다. 따라서 서버가 떠도 두 보조 ledger와 그 5개 index는 없을 수 있다.

assets, company_scope, llm_profiles, task_scope, mcp_servers의 일부 CHECK는 매 startup에 drop/add된다. ADD CONSTRAINT ... NOT VALID가 아니라 기존 row를 재검증하고 ALTER table lock이 일반 writer를 block할 수 있으며, invalid legacy row는 startup transaction을 실패시킨다. Initializer의 session advisory lock은 동일 initializer/archive 경로를 조율하지만 일반 DB connection의 쓰기를 자동으로 막지 않는다. Fresh/upgrade 제약 차이, repeated backfill·seed·default 변경은 migration 참조가 권위다.

배포 경로

소스 README는 Docker Compose, release binary+start.sh, source build를 제시한다. README 근거

Docker Compose 선언은 PostgreSQL 16 alpine의 named pgdata, ARTEX image, ./data:/app/data, ./skills:/app/skills, 8787 publish, 8788 loopback publish다. PostgreSQL health 후 ARTEX를 시작한다. 이는 manifest 정적 확인이며 실제 image/toolchain 또는 health를 실행 검증하지 않았다. compose 근거

source build는 Next.js static export를 server/webui/dist로 옮기고 -tags embedui Go binary를 만든다. release/설치 script의 요구 version과 dependency는 script가 권위이며 이 문서 생성 중 실행하지 않았다.

reverse proxy는 UI/API/SSE를 같은 8787 origin으로 넘기는 구성이 기본이다. SSE buffering을 끄라는 source README 지침이 있다. cross-origin dev path와 production same-origin path의 auth/CORS 차이는 HTTP 계약을 본다.

install.sh: 대화형 첫 설치

Script는 option을 받지 않고 먼저 Docker 전체 설치와 local build 중 하나를 묻는다. install script

Linux Docker 자동 설치는 원격 script 실행과 sudo usermod -aG docker "$USER"를 포함한다. Local config.json 생성은 JSON escape를 하지 않으므로 quote, backslash, newline이 든 credential은 invalid JSON을 만들 수 있다. Existing .env는 그대로 재사용하며 필수값 유효성을 script가 미리 확인하지 않는다.

dev.sh: source 개발 process group

./dev.sh는 go run ./cmd/artex -addr :8787 -proxy 127.0.0.1:8788과 web의 npm run dev를 병렬 시작한다. Frontend /api rewrite는 기본적으로 backend 8787을 향한다. EXIT/INT/TERM trap이 kill 0으로 같은 process group을 정리한다. Port나 binary flag를 argument로 바꾸는 인터페이스는 없다. Frontend override는 frontend env 5개를 쓴다. dev script

Script comment, banner, source README는 frontend URL을 http://localhost:5173으로 안내하지만 web/package.json의 command는 port 없이 next dev다. 이 checkout에는 PORT=5173을 주입하는 파일도 없다. 따라서 5173은 현재 command가 보장하는 값이 아니며 실제 listen port는 실행 환경/Next 동작을 확인해야 한다.

Build·package

• 현재 host/arch binary: ./build.sh
• 지정 target: ./build.sh --target linux/amd64
• default 5-target ZIP/checksum: ./build.sh --release
• static UI가 이미 준비된 CI build: ARTEX_SKIP_FRONTEND=1 ./build.sh --target linux/amd64

Option 5개, environment control 14개, 필수/optional executable, archive 내용은 직접 의존성·build 계약에 모았다. Build는 source/asset을 만들 뿐 실행 중 process를 재시작하지 않는다.

start.sh·start.bat: supervisor protocol

두 wrapper는 자신의 directory로 이동해 artex/artex.exe를 실행하고 받은 argument를 그대로 넘긴다. Unix wrapper Windows wrapper

Unix wrapper는 INT/TERM을 child에 TERM으로 전달하고 graceful exit를 다시 기다린다. Windows wrapper는 %* passthrough와 ping delay를 쓰지만 Unix와 같은 explicit signal-forwarding 경로는 없다. Self-update를 쓰면서 binary를 직접 실행하면 exit 75 뒤 자동 재기동되지 않는다.

Docker Compose lifecycle

docker compose up -d
docker compose logs -f artex
docker compose down

Production compose는 PostgreSQL health를 기다린 뒤 ARTEX를 실행하고 두 service 모두 unless-stopped다. down은 named pgdata volume을 기본 삭제하지 않지만 down -v는 삭제한다. Host persistence 선언은 ./data, ./skills, pgdata 세 곳이다. /app/jwt.key는 ./data:/app/data 밖이라 별도 보존해야 한다. Compose

docker-compose.bench.yml은 Dockerfile.bench와 bench/.env를 요구하지만 두 path가 이 source snapshot에 없다. 따라서 파일에 적힌 docker compose -f docker-compose.bench.yml up --build 절차는 현재 checkout만으로 실행 가능한 경로가 아니다. benchmark compose

업데이트와 rollback

update.sh

./update.sh는 CLI option이나 process env control을 읽지 않는 대화형 script다. 두 경로 모두 먼저 git pull --ff-only 실행 여부를 묻는다. Pull 실패는 warning만 내고 현재 checkout으로 계속한다. update script

Script는 DB schema를 직접 실행하지 않는다. 새 binary/container의 다음 startup이 embedded schema를 적용한다. Docker/local 어느 경로도 schema/data rollback을 제공하지 않는다.

In-app binary update artifact와 boot 판정

Artifact는 CWD가 아니라 현재 executable directory에 놓인다. Unix 예시는 아래와 같고 Windows는 .new.exe, .old.exe 순서다. self-update bootstrap

Apply 요청은 stage가 끝나면 exit 75를 내고 supervisor가 old binary를 다시 시작한다. Bootstrap이 candidate를 검증해 current/old를 swap한 뒤 다시 exit 75를 낸다. New binary가 HTTP listen 후 30초 생존하면 marker를 지워 settle한다. Marker가 남은 채 세 번 시작에 실패하면 다음 bootstrap이 .old를 복원한다. ARTEX_SELFUPDATE_SMOKE는 candidate의 -h child가 bootstrap을 재귀 실행하지 않게 하는 내부 env다.

이 rollback은 executable만 되돌린다. PostgreSQL schema/data, config.json, .env, data/skills directory는 과거 상태로 돌아가지 않는다. Update/restart는 실행 중 task를 중단할 수 있다.

reset-password.sh: 14개 option concept

Script는 administrator username ARTEX의 settings['auth.password_hash']를 PostgreSQL pgcrypto bcrypt cost 10으로 upsert한다. 성공하면 application restart 없이 다음 login부터 적용된다. password reset script

Local connection precedence는 explicit flags/--dsn → ARTEX_PG_DSN → selected config.json이다. Component path는 user와 dbname이 없으면 실패하고 host/port/sslmode만 기본값이 있다. Docker credential precedence는 flags → .env의 POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB → user/database artex; container는 postgres다.

Option 밖에서 명시적으로 소비하는 environment input은 5개다: local DSN fallback ARTEX_PG_DSN, libpq secret PGPASSWORD, Docker .env fallback POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB. Docker mode는 .env를 shell의 . ./.env로 source하므로 그 파일은 단순 key/value data가 아니라 현재 사용자 권한으로 평가되는 shell input이다.

ARTEX_RESET_NEWPASS는 script가 새 password를 psql \getenv에 전달할 때 임시로 export하고 끝에 unset한다. Component local path는 PGSSLMODE를 설정한다. -p와 -W로 secret을 주면 script가 이후 psql argv에는 넣지 않더라도 최초 shell/process argv에는 나타날 수 있으므로 interactive prompt나 사전에 보호한 environment/config가 더 적합하다. DB role에 CREATE EXTENSION IF NOT EXISTS pgcrypto 권한이 없으면 reset이 실패한다.

Task archive

task archive API는 archive row를 persistent queue에 넣고 background worker가 수행한다. archive 대상 task는 paused 또는 terminal이어야 하고 live dependent/source 관계에 따른 제한이 있다. package는 선별된 task-owned PostgreSQL tables, streamed LLM records, workspace/transcripts, scoped traffic, copied evidence를 .tar.zst로 모으며 checksum/format을 기록한다. DB snapshot에는 task/exploration graph, constraints/activity, relation/scope/assets, findings와 bound evidence, usage, pending intercept, side-question rows 등이 들어가지만 finding retest history와 그 conversation, intercept decision history, notification state는 query 목록에 없다. archive DB 근거 archive worker 근거

restore는 package checksum과 format/task id를 검증하고 traffic/files/DB를 단계적으로 설치한 뒤 package를 consume한다. stage journal과 startup recovery path가 archive/restore/delete 중단을 다룬다. 클라이언트는 enqueue 응답이 아니라 task_archives.state, phase, progress, error, warnings로 결과를 판단해야 한다.

Archive compaction은 PostgreSQL commit 후 staged Traffic SQLite delete를 commit하므로 두 store가 하나의 atomic transaction이 아니다. 그 사이 crash gap은 traffic staging journal과 startup recovery가 PostgreSQL archive state를 조회해 보정한다. Restore에서는 incoming archive blob을 SHA-256 검증하고 CAS copy한 뒤 SQLite transaction을 연다. 이미 존재하는 destination blob은 재검증하지 않으며, 후속 DB 실패·duplicate-only import에 orphan이 남을 수 있다. FTS는 small body 전체 또는 spilled body의 archive inline 8 KiB preview로 재생성된다. Traffic commit/recovery matrix

Backup·복구 경계

Task archive는 한 task의 cold storage/restore 기능이다. 다음을 모두 포함하는 전체 disaster-recovery backup은 아니다.

• PostgreSQL 전체와 global settings
• 모든 task와 archive stub/package
• config.json, .env, provider/MCP/notification secrets
• jwt.key
• 전체 skills
• data directory의 task 밖 파일

또한 해당 task와 연결돼 보여도 finding retest history/conversation처럼 snapshot query에 없는 기능 데이터는 복원되지 않는다. archive를 task의 모든 이력 보존으로 간주해서는 안 된다.

저장소에서 완전한 PostgreSQL backup/restore script, RPO/RTO 선언, isolated restore test 절차는 확인되지 않았다. pgdata volume persistence도 backup 자체는 아니다. 실제 운용 전 DB와 filesystem을 일관된 시점에 보존하고 복구 rehearsal하는 절차를 별도로 설계해야 한다.

Traffic root/index/CAS/CA는 코드상 0755, CAS blob은 0644, archive staging/blob directory는 0700, archive/journal file은 0600을 요청한다. Umask·ACL·container volume mount가 effective permission을 바꿀 수 있으며 실제 mode/owner는 관찰하지 않았다.

관찰과 상태 판정

실제 readiness에는 PostgreSQL, 선택한 LLM chain, 외부 MCP/search, target egress, proxy CA, filesystem 여유가 함께 필요하다. /health 하나만으로 이 의존성을 증명하지 않는다.

원본 배포물의 사용 제한

고정한 upstream README의 “许可与免责声明” 구역은 ARTEX를 개인 학습·코드 연구·로컬 격리 검증에만 쓰고, 승인 여부와 관계없이 웹사이트·온라인 서비스·네트워크 시스템에 실제 scan/probe/exploit을 하지 말라고 명시한다. 원문 위치

이 문구는 이 문서에서 확인한 runtime scope control과 별개의 배포물 사용 조건이다. AGPL-3.0 license text와 README의 추가 조건이 어떤 법적 관계를 갖는지는 이 기술 문서가 판단하지 않는다. 프로젝트가 ARTEX 코드를 재사용·배포·운용하려면 별도의 법률·라이선스 검토 대상이다.

실행 전 확인할 미검증 항목

• 실제 PostgreSQL에 전체 schema가 적용되고 expected tables/indexes/checks가 존재하는가
• container recreate 뒤 jwt.key, traffic CA, evidence, transcripts가 유지되는가
• task archive round trip이 큰 body/LLM record/상속 task에서도 복원되는가
• update 직후 schema change와 binary rollback 조합이 안전한가
• reverse proxy에서 SSE buffering, timeout, query token log redaction이 맞는가
• traffic proxy 실패/transparent tunnel이 evidence completeness에 어떻게 표시되는가
• DB/file backup을 같은 복구 시점으로 맞출 수 있는가

상위 영역: ARTEX 현재 시스템 지도

전체로 돌아가기 · Markdown 원본