AI Fabrix Builder Server Setup (af-server)

This is the one document you need to get your builder-server from zero to up and running in your own Docker. How to use the server (users, secrets, onboarding, etc.) is in the AI Fabrix Builder CLI documentation—full open source: github.com/esystemsdev/aifabrix-builder.

Why AI Fabrix Builder server?

• Full AI Fabrix platform, one server, multi-developer: You run the full AI Fabrix platform and a separate builder-server where multiple developers each get their own dedicated, isolated environment (users, certificates, secrets, workspaces). One installer (af-server) sets up Docker, nginx, SSL proxy, sync user, and backup on that server.
• One tool for install and management: The same AI Fabrix Builder CLI gets you the platform and manages users, secrets, and onboarding. All how-to in Builder CLI docs.
• Security and standards: TLS, client certificates, no secrets in version control. Backups are explicit (config + DB + keys); store them encrypted.

Getting the builder-server Docker image

The builder-server Docker image is not on a public registry. You get it with the AI Fabrix platform.

1. Install the AI Fabrix Builder CLI: npm install -g @aifabrix/builder
2. Install the AI Fabrix server-setup CLI (af-server): npm install -g @aifabrix/server-setup
   • If you get EACCES (permission denied), use either:
     sudo npm install -g @aifabrix/server-setup
3. Use the Builder CLI to run or deploy the platform (including builder-server). See AI Fabrix Builder and docs/README.md.

Once you have the platform (and the builder-server image), use af-server to install that server on your own host.

Prerequisites

• Node.js ≥ 18 (where you run af-server)
• SSH access to the server (key-based auth). af-server uses ~/.ssh/id_ed25519.pub or ~/.ssh/id_rsa.pub by default; use -i path/to/key if your key is elsewhere.
• Server: Ubuntu. For remote install the script can install Docker; you provide domain, SSL directory, and certificates (next section).

Manual prerequisites (before install)

Do the steps in What you must do before running af-server (below): Ubuntu version, root/sudo, SSH, DNS (CNAME or A), SSL directory, and certificate + key. The install script does not create or obtain certificates; it configures nginx to use the files you provide.

Install: from zero to running

Complete the manual prerequisites first (DNS, SSL directory, certificate and key on the server).

Flow summary: Only step 1 runs over SSH from your PC. Steps 5 and 7 run on the server after you log in, so errors and output are visible directly there.

| Step | Where | Action | | ---- | --------- | ------ | | 1 | From PC | af-server install-init $SSH — only command over SSH; installs on server: SSH (if needed), Node 20+, npm, and af-server CLI. | | 2 | One-time | Log in to the server once (e.g. with password) to approve passwordless SSH; then from PC: af-server ssh-cert install $SSH. | | 3 | From PC | Copy SSL certificate and key to the server (see SSL directory and certificates); example commands below. | | 4 | From PC | Log in to the server via SSH (passwordless). | | 5 | On server | sudo af-server install — install all services (Docker, nginx package, Mutagen, cron, data dir); no builder-server container yet. | | 6 | On server | Get the builder-server image (e.g. az login / docker pull). | | 7 | On server | sudo af-server install-server --dev-domain $DOMAIN — nginx vhost, builder-server container, Docker TLS. | | 8 | — | Done. |

Step 1: Bootstrap the server (from PC)

Set your target and run the only command that uses SSH from your PC:

export [email protected]
af-server install-init $SSH

This installs on the server: openssh-server (if needed), Node 20+, npm, and @aifabrix/builder + @aifabrix/server-setup so af-server is available there. You’ll see progress messages and live output from the bootstrap (package lists, SSH, Node, npm install). No Docker, nginx, or builder-server yet.

Step 2: Passwordless SSH (from PC)

Log in to the server once (e.g. with password) to accept the host key and/or approve auth. Then from your PC:

af-server ssh-cert install $SSH

Step 3: Copy SSL (from PC)

Put wildcard.crt and wildcard.key in /opt/aifabrix/ssl on the server. Example (replace $HDD with the folder on your PC that has the cert and key):

export HDD=/workspace/aifabrix-setup/certificates
ssh $SSH "sudo mkdir -p /opt/aifabrix/ssl"
scp $HDD/wildcard.crt $SSH:/tmp/wildcard.crt
scp $HDD/wildcard.key $SSH:/tmp/wildcard.key
ssh $SSH "sudo mv /tmp/wildcard.crt /tmp/wildcard.key /opt/aifabrix/ssl/ && sudo chmod 600 /opt/aifabrix/ssl/wildcard.key"

Step 4: Log in to the server

ssh $SSH

Step 5: Install services (on server)

sudo af-server install

This installs Docker, nginx (package only), Mutagen, data dir, apply-dev-users script and cron. It does not write the builder nginx vhost or start the builder-server container.

Step 6: Get the builder-server image (on server)

The image is not on a public registry. Use your platform’s method (e.g. Azure CLI or Docker login), then pull. Example:

az login
az acr login --name youracr
docker pull youracr.azurecr.io/aifabrix/builder-server:latest

Or with Docker login (username/password from your registry):

docker login <registry> -u <user> -p <password>
docker pull <registry>/aifabrix/builder-server:latest

Step 7: Install server (nginx vhost + container) (on server)

export DOMAIN=builder02.aifabrix.dev
sudo af-server install-server --dev-domain $DOMAIN

Use the same domain as your DNS and SSL. Optional: --ssl-dir /opt/aifabrix/ssl, --data-dir /opt/aifabrix/builder-server/data, --builder-port 3000.

If the builder-server image is not on the host yet, the first run writes an nginx vhost without client-cert verification (so nginx -t passes). After you pull the image and re-run sudo af-server install-server --dev-domain $DOMAIN, the container will start, create ca.crt, and a subsequent run will enable client-cert verification and reload nginx.

Step 8: Done

Your builder-server is up. Use the AI Fabrix Builder CLI for users, secrets, certs, etc.—see Builder documentation.

Commands

| Command | Description | | -------- | ----------- | | af-server install-init <user@host> [ -i SSH_KEY ] | From PC only. One-time bootstrap over SSH: install on server SSH (if needed), Node 20+, npm, and af-server CLI. Shows progress and streams server output. | | af-server install [ user@host ] [ -d DATA_DIR ] [ --dev-domain DOMAIN ] [ --ssl-dir PATH ] [ -i SSH_KEY ] | Run on server (omit target): sudo af-server install. Infra only: Docker, nginx pkg, Mutagen, data dir, cron. No builder vhost or container. With target: same infra over SSH. | | af-server install-server --dev-domain DOMAIN [ -d DATA_DIR ] [ --ssl-dir PATH ] [ --builder-port PORT ] | On server only. Nginx vhost, builder-server container, Docker TLS. Run after sudo af-server install. | | af-server backup [ user@host ] [ -d DATA_DIR ] [ -o output.zip ] [ -i SSH_KEY ] | On-demand backup (config + DB + keys). | | af-server backup [ user@host ] --schedule [ --backup-dir PATH ] [ --keep-days N ] [ -i SSH_KEY ] | Cron backup (daily 02:00, keep last N, default 7). | | af-server restore backup.zip [ user@host ] [ -d DATA_DIR ] [ --force ] [ -i SSH_KEY ] | Restore backup to DATA_DIR. | | af-server ssh-cert install [ user@host ] [ -i SSH_KEY ] | Add your SSH public key to server (passwordless auth). | | af-server install-ssh [ user@host ] [ -i SSH_KEY ] | Activate SSH server (install openssh-server, enable and start ssh) without login. Omit target for local. |

Backups contain secrets; store encrypted. Cron backup needs SQLite (builder.db) and zip on the server; default backup dir: /opt/aifabrix/backups.

Documentation

All how to use the builder-server (users, secrets, onboarding, developer isolation, etc.) is in the open-source AI Fabrix Builder docs:

• AI Fabrix Builder — repo and README
• docs/README.md — full documentation index

This README is only: zero to up and running your builder server.

What you must do before running af-server

Complete these manually before af-server install. The install script does not create DNS, certificates, or the admin account; it expects them to exist.

Server and access

• Ubuntu — 22.04 LTS or later (recommended). Other Debian-based systems may work but are not guaranteed.
• Root or sudo — The install script must run with root (or sudo). From your PC you SSH as a user that can sudo to root; on the server you run sudo af-server install (or as root).
• SSH access — You need key-based or password SSH to the server so you can run af-server install user@host, or you run install locally on the server.

DNS (CNAME or A record)

• Create a DNS A record or CNAME so your chosen domain points to the server’s IP.
• Default domain used by the script: builder01.aifabrix.dev. To use another domain, set --dev-domain or env DEV_DOMAIN.
• Ensure DNS has propagated before install (nginx will use this domain).

SSL directory and certificates

• Create the SSL directory (default /opt/aifabrix/ssl):
  sudo mkdir -p /opt/aifabrix/ssl
  To use another path, set --ssl-dir or env SSL_DIR.
• Obtain a TLS certificate and private key (e.g. Let’s Encrypt, internal CA, or purchased). Full chain if applicable.
• Place in the SSL directory:
  • wildcard.crt — certificate (full chain if applicable)
  • wildcard.key — private key
    Set permissions: chmod 600 /opt/aifabrix/ssl/wildcard.key
    If your files have other names (e.g. fullchain.pem / privkey.pem), symlink them to wildcard.crt and wildcard.key.
• The install script does not create or obtain certificates; it only configures nginx to use these files.

Admin user (optional but typical)
If you SSH as a non-root user, that user must be able to sudo. The script will add an admin user (default serveradmin) to the docker group and grant it passwordless sudo. Ensure that user exists on the server if you rely on it, or set SETUP_ADMIN_USER to your SSH user.

High level: what install vs install-server does

af-server install (step 5 — run on the server) does infra only:

• System — apt update and apt upgrade; optional hostname if SETUP_HOSTNAME is set.
• Docker — Installs Docker if missing; enables and starts it.
• Admin user — Adds the admin user (default serveradmin) to the docker group and grants passwordless sudo.
• Nginx — Installs the nginx package only; enables and starts it. Does not write the builder vhost yet.
• Data dir — Creates the data directory (default /opt/aifabrix/builder-server/data), workspace and ssh-keys subdirs, ownership for the container.
• Apply-dev-users — Installs the script and cron job (every 2 minutes) that sync per-developer OS users from builder-server state. The script configures a user-writable npm/pnpm prefix (~/.local) for dev users and the aifabrix user so they can run npm install -g and pnpm add -g without sudo. When run as root, it can also grant passwordless sudo to the aifabrix user (override with SUDO_NOPASSWD_USER in apply-dev-users-defaults). Without sudo: run the script as the current user (e.g. SUDO_NOPASSWD_USER=aifabrix); it will only set up that user's ~/.local and ~/.npmrc/~/.pnpmrc so npm and pnpm global installs work without sudo.
• Mutagen — Downloads and installs Mutagen; systemd service and daemon.
• Optional — If INSTALL_PORTAINER=1, installs the Portainer container.

af-server install-server (step 7 — run on the server) does the server phase:

• Nginx vhost — Writes the builder site config from template (domain, SSL dir, proxy to builder-server), reloads nginx.
• Builder-server container — Creates data dir (if needed), starts the builder-server container (if the image is present).
• Docker TLS — Copies certs and configures /etc/docker/daemon.json for TLS (using website cert and builder-server CA).

Result: after both steps, the server has Docker, nginx (HTTPS for your domain), the builder-server container (if image present), and Mutagen—ready for the Builder CLI to use.

Troubleshooting

af-server --version shows an old version after installing a newer one

If you ran sudo npm install -g @aifabrix/[email protected] but af-server --version still reports an older version (e.g. 1.5.3):

1. Check which binary is used
   Run which af-server and sudo which af-server. If they differ, your shell may be using a user-level install while the new one was installed for root.

2. Uninstall, clear cache, then reinstall

   sudo npm uninstall -g @aifabrix/server-setup
   npm cache clean --force
   sudo npm install -g @aifabrix/[email protected]
   hash -r   # clear shell’s command cache
   af-server --version