Organization Configuration

Complete installation and first-admin setup before configuring your organization. Organization administration is available to administrators under Settings → Organization.

Organization Members

Administrators can create members, change administrator/member roles, reset passwords, disable accounts, and reassign project stewardship.

• Create a member: provide a name, email, initial password, and role. Deliver the password through your organization's approved channel.
• Reset a password: select Manage, enter a new password, and save. Existing sessions are revoked.
• Disable a member: select Manage, enable Disable this member, and save. Sign-in and API access are revoked, while projects, groups, and history remain.
• Reassign stewardship: select the departing member and the recipient. Their projects move to the recipient, who also receives ownership in the departing member's groups. Existing sharing and other owners remain.

An administrator cannot disable their own account, and the organization must retain at least one active administrator. Organization members are retained rather than deleted so their architecture data is not removed through cascading account deletion.

Organization membership and project access are separate. Use project sharing and groups to grant the intended access.

Organization AI

Configure shared AI in the administrator interface:

1. Sign in as an organization administrator and open Settings → Organization → Configure organization AI.
2. Enable Allow managed AI.
3. Choose the Provider and enter the Model available from that provider.
4. Set Base URL when your provider requires a custom endpoint, such as an internal model server.
5. Enter the API key if the provider requires one.
6. Review the usage and token limits, then select Save settings.

The web application and background worker use this administrator-managed configuration. Return to this screen to change providers, models, endpoints, or credentials. The interface uses the label managed AI for the organization's shared provider.

Personal and project provider overrides are not used in single-org mode. Project automation switches, concurrency and token limits, reservations, and usage budgets still apply.

For private processing, choose an internal model endpoint reachable by the web and worker containers. localhost inside a container refers to that container, not another server or the host machine. Configuring a public AI provider allows the required architecture context to leave your network for processing by that provider.

AI is optional. Leave organization AI disabled to use the architecture editor without AI-assisted generation or analysis. See network privacy before enabling integrations.

Optional SMTP

Set these values in .env.self-host when email delivery is required:

SMTP_HOST=mail.internal.example
SMTP_PORT=587
SMTP_FROM=archflow@example.com
SMTP_USER=your-smtp-user
SMTP_PASSWORD=your-smtp-password

Leave username and password blank if your SMTP server does not require authentication. Port 465 uses implicit TLS; other ports use SMTP with STARTTLS when the server advertises it. The same transport serves web emails and worker notifications.

Without SMTP, members still sign in with passwords and administrators can reset them. Email-based recovery reports that delivery is unavailable; optional notification jobs are logged as skipped.

Recreate web and worker after changing environment settings:

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

External S3 Storage

The default SeaweedFS service provides S3-compatible storage inside the installation. To use another service, first create a private bucket and grant its service identity permission to list the bucket and read, write, and delete its objects.

Set the following in .env.self-host:

S3_ENDPOINT=https://s3.internal.example
S3_BUCKET=archflow
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=your-access-key
S3_SECRET_ACCESS_KEY=your-secret-key
S3_FORCE_PATH_STYLE=true

Use the external-storage override supplied with your installation package. With Compose 2.24.4 or newer, layer it after the base file. First pull or load the required images as described in setup, then start the installation:

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

The override removes web and worker's dependency on bundled SeaweedFS and places that service behind an inactive profile. AWS S3 normally uses S3_FORCE_PATH_STYLE=false with its regional endpoint.

Include both -f arguments when pulling images and in subsequent status, upgrade, and maintenance commands. If your received files use different names, substitute those names. Browsers access files through Archflow; they do not need bucket credentials or bucket CORS rules. Changing storage providers also requires transferring existing objects, not just changing the endpoint.

Deployment Mode

The supplied Compose file selects ARCHFLOW_DEPLOYMENT_MODE=single-org and ARCHFLOW_STORAGE_DRIVER=s3. Keep those settings for the default self-hosted stack.

A database initialized for a single organization refuses to start in hosted mode. Setup also refuses a database containing existing hosted users. Converting an existing hosted deployment requires a separate data migration; switching the environment flag alone is not a conversion procedure.