Self-host ArtifactFlow

Local evaluation

Start with Docker Compose and GNU make.

The local stack targets PHP 8.5, Laravel 13, PostgreSQL, Caddy, and FrankenPHP, but those runtimes live inside containers. You need Docker with Compose v2 and GNU make. Contributors running the full quality suite also need Node.js, npm, Python, and Semgrep.

git clone https://github.com/Gadsotek/artifactflow
cd artifactflow
make up
make shell
php artisan artifactflow:install

The guided installer runs inside the application container after the stack is reachable. Choose the local environment, create the first System Admin, optionally seed demo content, then sign in at http://localhost:18080/login.

Development stack only

The bundled Compose file uses local credentials and non-TLS services. It is not a production deployment template and should not be presented as one.

Mandatory production topology

One code image serves separate trust boundaries.

The supported production unit is the repository's Dockerfile-built image with APP_ENV=production. The runtime role and container command determine which responsibility each instance owns.

appAuthenticated browser UI, sessions, editing, search, workspace management, MCP, and preview-grant issuance on the application hostname.
artifact-hostCookieless static artifact execution on a different hostname, accepting only signed saved previews and content-bound draft previews.
workerQueue processing in a non-serving role using the same immutable image.
schedulerScheduled maintenance in a non-serving role using the image's scheduler start command.

The app and artifact-host instances must mount the same private artifact store; the artifact-host side should be read-only where the storage platform permits it. Application cookies must never be sent to the artifact hostname.

Operator-provided services

A production environment has a concrete security contract.

Two HTTPS hostnamesOne application origin and one artifact origin, with correctly preserved external scheme, host, and port through the trusted proxy.
PostgreSQL with verified TLSProduction requires server-identity verification, including DB_SSLMODE=verify-full and a trusted database CA.
Private persistent artifact storageSaved HTML must not be web-accessible outside the artifact-host authorization path and must be backed up consistently with PostgreSQL.
Independent secretsAPP_KEY and a dedicated high-entropy ARTIFACT_URL_SIGNING_KEY come from a secret manager and must not be reused.
Mail and proxy deliveryA deliverable mail configuration, correct TLS termination, response headers, request-size limits, and host routing are part of the deployment.
Shared rate-limit state for replicasMultiple app replicas need shared rate-limit storage so authentication and preview limits do not fragment per container.

The base product does not require Redis, Meilisearch, S3, or SSO. Operators may choose suitable infrastructure, but a deployment must preserve the documented security behavior rather than copying development defaults.

Fail closed

The image refuses an incomplete production contract.

Production boot validates the runtime role, distinct origins, signing keys, frame-ancestor policy, private storage, database TLS, mail, administrative bootstrap path, and other security-critical settings. An unsafe combination stops startup instead of degrading into a less isolated mode.

Before the schema is ready, application-origin browser and MCP requests also stop at an installation-readiness boundary before database sessions or bearer-token lookup. Browsers receive a secured setup response, MCP receives a retryable JSON-RPC 503, and only the session-free /up health endpoint remains available. The artifact origin does not disclose setup state.

Readiness is cached only for the exact migration-file manifest, so deploying a new migration invalidates success immediately. Run the guided installer for a first installation or the approved migration workflow for an existing one.

First production install

Provision configuration before the first serving container starts.

Supply production variables from the platform's secret manager. Run the installer as a one-off container with the same image and environment, passing the first administrator password through a mounted secret file. Then run the deployment doctor before starting every serving role.

docker run --rm --env-file <production-env> <image> \
  php artisan artifactflow:install \
  --env=production --name='Ops' --email='[email protected]'

docker run --rm --env-file <production-env> <image> \
  php artisan artifactflow:doctor

The exact storage mounts, secret-file path, network policy, database endpoint, hostnames, and service orchestration depend on the deployment platform. The operations guide is authoritative for those details.

Operate the whole system

Backups and releases include data, artifacts, and key custody.

Consistent recovery needs a PostgreSQL dump and the private artifact tree, validated together by the repository's backup workflow. APP_KEY and the artifact signing key are deliberately not copied into data backups, so secret-manager custody and recovery procedures must be tested separately.

Before inviting users, complete the alpha release checklist, verify signed preview behavior in supported browsers, run the deployment doctor, validate backup restoration, and keep the dependency, test, build, and image-scan gates green.

Related guides

Carry the same boundary from architecture to operations.

Operations guide ↗Environment, roles, storage, database, proxy, backup, restore, and release procedures. Alpha release checklist ↗Pre-release gates and manual security checks. Security architectureHow two origins, iframe sandboxing, CSP, and signed grants fit together. MCP serverScope automation clients within the application trust boundary.