Install And Set Up

Use the Docker Compose file and prebuilt images you received with your Archflow installation package. The package provides environment configuration instructions and either registry access or image archives. No application source checkout or image build is required.

The commands below use compose.self-host.yml and .env.self-host. If your received files have different names, use those names in the commands. Keep the deployment files in a dedicated installation directory.

Requirements

• Docker Engine or Docker Desktop with Docker Compose v2. Use Compose 2.24.4 or newer if you need the external-S3 override.
• The received Compose file, configuration instructions, and prebuilt images for your Docker host.
• A clean application database and persistent disk space for the database, queue, and files. Compose provisions these services and their volumes.
• Access to the supplied image registry or an internal mirror, unless you received image archives for an offline installation.
• An HTTPS reverse proxy if people will connect beyond the local machine.

Azure, an AI account, and an email service are not required for the initial installation. SeaweedFS provides private S3 storage in the default stack.

1. Prepare Local Configuration

Create .env.self-host in the installation directory using the configuration generator or template supplied with your package. Follow the received instructions to generate fresh database, storage, authentication, encryption, and setup secrets locally. Do not reuse example secrets.

Restrict access to this file to the administrator running the installation. Configuration does not require registering the installation or activating an online license.

Keep this file out of source control and include it in secure backups. Preserve ENCRYPTION_KEY: changing it prevents decryption of stored provider credentials.

2. Set The Installation URL

Edit .env.self-host and set the address members will open:

ARCHFLOW_URL=https://architecture.example.com
ARCHFLOW_PORT=3000

For a local evaluation, set ARCHFLOW_URL=http://localhost:3000. If you want to open http://127.0.0.1:3000, set ARCHFLOW_URL to that exact address instead. Scheme, hostname, and port must match: browsers treat localhost and 127.0.0.1 as different origins.

The application port binds to 127.0.0.1 by default. For access beyond the local machine, place your HTTPS reverse proxy in front of the application and preserve the original host and forwarded protocol. ARCHFLOW_BIND_ADDRESS changes the bind address when your network layout requires it. Database, queue, and storage ports are not published by the supplied Compose file.

3. Obtain Images And Start

Use the delivery method included with your installation package.

If you use an existing S3 service, follow external storage configuration and include its override in every Compose command.

With Registry Access

Sign in to the registry using the credentials you received. Replace REGISTRY_HOST with the supplied registry hostname; Docker prompts for your credentials.

docker login REGISTRY_HOST
docker compose --env-file .env.self-host -f compose.self-host.yml pull

The received Compose file identifies the images and release versions to download. Use the supplied references or the corresponding references in your internal mirror.

With Image Archives

Load each image archive you received. Replace archflow-images.tar with the actual archive filename:

docker load --input archflow-images.tar

For an offline installation, load every image referenced by the Compose file, including PostgreSQL, Valkey, and SeaweedFS when bundled. Image names and tags must match the received Compose file.

Start The Installation

After the images are available locally, run:

docker compose --env-file .env.self-host -f compose.self-host.yml up -d --no-build --pull never

Compose starts the supplied images and applies database migrations. It does not build or download images in this step. Web and worker start after migrations succeed and the queue and storage services are healthy.

Check progress:

docker compose --env-file .env.self-host -f compose.self-host.yml ps -a
docker compose --env-file .env.self-host -f compose.self-host.yml logs --tail 100 web worker migrate

The migrate service should exit with code 0. See operations if web or worker cannot start.

4. Create Your Organization

Open the exact ARCHFLOW_URL you configured. An uninitialized installation sends you to /setup.

Enter:

1. The setup key from ARCHFLOW_SETUP_TOKEN in .env.self-host.
2. Your organization name.
3. The first administrator's name and email address.
4. A password of at least 12 characters and its confirmation.

Select Create organization. Setup creates the organization and administrator together and signs you in. No email verification or external account is needed. The setup endpoint closes after successful initialization; simultaneous requests cannot create competing first administrators.

Keep ARCHFLOW_SETUP_TOKEN in the deployment environment after setup. Startup validation still requires it even though organization creation is closed.

5. Add Members

Open Settings → Organization. Under Add a member, enter the person's name, email, initial password, and role. Share the initial password through your organization's approved channel.

Members sign in at your installation URL. There is no public signup. Grant access to projects through the existing project and group sharing controls.

6. Configure Optional Services

The architecture editor is ready without AI or email. To enable AI, an administrator opens Settings → Organization → Configure organization AI, enters the provider settings, and saves them. Follow organization AI setup for the steps. Email delivery is configured separately through SMTP settings.

Then follow the Quickstart to create the first architecture project.

Invalid Request Origin

If setup reports Invalid request origin, compare the address bar with ARCHFLOW_URL. Open the configured address, or update ARCHFLOW_URL and recreate web and worker:

docker compose --env-file .env.self-host -f compose.self-host.yml up -d --no-build --pull never --no-deps web worker

A plain container restart does not reload environment values. This check protects setup and organization changes from cross-site requests; do not disable it to work around a URL mismatch.