setupsetup-guide

ABS Setup Guide

Install your self-hosted ABS server in about 30 minutes

Welcome! This guide will walk you through deploying your own ABS instance on a Linux VPS using Docker Compose. Your welcome email contains three essential attachments: docker-compose.yml, Caddyfile, and .env.template. You will receive a separate email with your ABS_LICENSE_KEY within 24 hours of purchase, which is required to complete the setup. Let's get started.

1. Prepare your VPS

We recommend a Hetzner CX22 cloud server, which offers excellent value at around €3.79/month. The minimum requirements are Ubuntu 22.04 LTS (or a similar modern Linux distribution), 2 vCPUs, 4 GB of RAM, and 40 GB of disk space. Once your server is running, create a DNS A record for your chosen subdomain (e.g., abs.yourdomain.com) and point it to your server's public IP address. Next, configure your firewall to allow essential traffic. Using ufw, run ufw allow 22/tcp, ufw allow 80/tcp, and ufw allow 443/tcp, then ufw enable. For security, create a non-root user with sudo privileges and configure SSH key-based authentication, disabling password login. This user will run the installation. Finally, make a note of your full subdomain, as you will need it for the ABS_PUBLIC_HOSTNAME variable later.

# Point an A record at your VPS public IP, then on the server:
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo adduser abs && sudo usermod -aG sudo abs
ssh-copy-id abs@your.hostname.com

2. Install Docker and authenticate to GHCR

First, install Docker Engine and Docker Compose. The simplest way is to run the official convenience script: curl -fsSL https://get.docker.com -o get-docker.sh followed by sh get-docker.sh. After installation, add your non-root user to the docker group with sudo usermod -aG docker $USER. You must log out and log back in for this change to take effect. Verify your setup by running docker run hello-world. Next, you need to authenticate to the GitHub Container Registry (GHCR) to pull the private ABS images. Your welcome email contains a unique, read-only Personal Access Token (PAT). Use it to log in by running docker login ghcr.io -u YOUR_GITHUB_USERNAME -p YOUR_PAT. This token is for pulling images only and should be kept private.

curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh
sudo usermod -aG docker $USER
# log out, log back in
docker run hello-world
docker login ghcr.io   # paste read-only PAT from your welcome email

3. Save the three attached files and fill .env

Create a dedicated directory for your ABS configuration. We recommend /opt/abs. Run sudo mkdir /opt/abs and sudo chown $USER:$USER /opt/abs, then cd /opt/abs. Download the three attachments from your welcome email (docker-compose.yml, Caddyfile, and .env.template) into this directory. Now, you need to configure your instance. Make a copy of the template with cp .env.template .env and open .env in a text editor. You must fill in three required values: ABS_LICENSE_KEY (from your separate license email), ABS_PUBLIC_HOSTNAME (e.g., abs.yourdomain.com), and ABS_ACME_EMAIL (for Let's Encrypt SSL certificate notifications). You can also add API keys for providers like OpenAI, Anthropic, or Groq. If you leave these blank, ABS will simply not make calls to those providers. Save the file when you're done.

sudo mkdir -p /opt/abs && sudo chown $USER:$USER /opt/abs
cd /opt/abs
# save docker-compose.yml, Caddyfile, .env.template here
# (download from your welcome email attachments)
nano .env.template   # fill ABS_LICENSE_KEY, ABS_PUBLIC_HOSTNAME, ABS_ACME_EMAIL
mv .env.template .env

4. Bring ABS up with docker compose

With your configuration in place, you're ready to start the server. From your /opt/abs directory, run docker compose -f docker-compose.yml up -d. This command will pull the necessary images from GHCR and start all the services in the background. It can take a few minutes for the initial pull and startup. You can monitor the progress by tailing the logs with docker compose logs -f. Wait for the backend service's health check to turn green, which usually takes about 60 seconds. During this time, the caddy service will automatically request and install a free TLS certificate from Let's Encrypt. This requires that your DNS A record is live and ports 80 and 443 are open. Once it's up, you can verify the backend is healthy by running curl https://your.hostname.com/healthz.

cd /opt/abs
docker compose -f docker-compose.yml up -d
docker compose logs -f      # wait ~60s for backend healthcheck
curl https://your.hostname.com/healthz

5. First-run setup wizard

Now that the services are running, open your web browser and navigate to your ABS hostname, e.g., https://abs.yourdomain.com. You will be greeted by the first-run setup wizard. This simple process configures the initial administrative user for your instance. You'll be asked to provide an admin email and create a strong password. You will also have the option to set a vault key for encrypting secrets at rest and to enter any provider API keys if you didn't set them in the .env file. The wizard will validate your ABS_LICENSE_KEY against our licensing server and fingerprint the installation to your domain. Upon successful completion, you will be redirected to the main ABS admin panel, ready to start orchestrating.

# Open in your browser:
# https://your.hostname.com
# Wizard:
#   1. Admin email + password
#   2. Optional vault key
#   3. Optional provider keys (Anthropic / OpenAI / Groq / Cohere)
#   4. License JWT validation

Troubleshooting

Don't worry, most setup issues are easy to fix. They usually involve DNS propagation, firewall rules, or a typo in a token.

GHCR authentication fails

If docker compose up fails with an unauthorized error while pulling images, your GHCR token is likely incorrect or has expired. Use the link in your welcome email to re-issue a new Personal Access Token. Then, run docker login ghcr.io again with the new credentials. You can verify the stored credentials in ~/.docker/config.json.

docker login ghcr.io
cat ~/.docker/config.json | grep ghcr.io

License activation timeout

If the backend logs show errors like license activation failed: context deadline exceeded, it's often due to the container not being able to reach our licensing server. This can be caused by clock skew or a restrictive egress firewall. Ensure your server's time is synchronized by running sudo timedatectl set-ntp true. Also, make sure your firewall allows outbound HTTPS traffic to *.workers.dev.

sudo timedatectl set-ntp true
sudo timedatectl status
curl -I https://abs-license-activation.automatiaabs.workers.dev

Caddy can't issue a TLS certificate

If you see TLS or certificate errors in the caddy logs, it means Let's Encrypt couldn't verify your domain. The most common causes are that your DNS A record hasn't fully propagated or your firewall is blocking ports 80 and 443. Verify DNS with dig +short your.hostname.com. It must return your VPS IP. Check your firewall with sudo ufw status and ensure ports 80 and 443 are allowed.

dig +short your.hostname.com
sudo ufw status
docker compose logs caddy | tail -50

Backend out of memory

If the backend container is in a restart loop or you see OOM (Out of Memory) errors in the logs, your server may be under-resourced. The 4 GB RAM minimum is tight, especially if you're running local embedding models. Consider upgrading your VPS to a plan with 8 GB of RAM, like the Hetzner CX31. Alternatively, you can offload memory-intensive tasks by providing API keys for external embedding providers in your .env file.

docker stats --no-stream
docker compose logs backend | grep -i 'oom\|memory'
# free -h to check host memory

Cannot reach the admin panel

If you see a 502 Bad Gateway error after Caddy is up and has a certificate, it usually means the landing container is unhealthy and Caddy can't proxy to it. Check its logs with docker compose logs landing. A common cause is a missing or incorrect ABS_PUBLIC_URL in your .env file. It must be set to your full URL, like ABS_PUBLIC_URL=https://abs.yourdomain.com. After fixing it, run docker compose restart landing.

docker compose logs landing | tail -50
# In .env, ensure:
# ABS_PUBLIC_URL=https://your.hostname.com
docker compose restart landing

Need a hand?

If you're still stuck, we're here to help. Just reply to your welcome email or send a message to founder@automatiabcn.com. Please include the output of docker compose logs so we can diagnose the issue quickly. Most problems are solved in a single email exchange.

ABS