setupsetup-guide

ABS: Setup Guide

From `git clone` to a running ABS in ~5 minutes.

This guide walks you through deploying your own ABS instance with Docker Compose. The repo at github.com/automatiabcn/abs is public, no GHCR token, no attachments. Your welcome email contains your ABS_LICENSE_KEY; that's all the secret you need.

1. Prepare your server

ABS runs on any Linux host that can run Docker. We recommend Ubuntu 22.04+, 2 vCPU, 4 GB RAM and 40 GB disk, a Hetzner CX22 (€3.79/mo) is a perfect fit. Point a DNS A record (e.g. abs.yourdomain.com) at the server's public IP, open ports 22/80/443, then install Docker. Caddy (bundled in our compose file) will handle TLS automatically once the DNS resolves.

# Any Linux host with Docker. Hetzner CX22 (€3.79/mo) works great.
# Point an A record at the server's public IP first.
sudo ufw allow 22/tcp && sudo ufw allow 80/tcp && sudo ufw allow 443/tcp && sudo ufw enable
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER   # then: log out, log back in
docker run hello-world

2. Clone the public repo

ABS lives in a public GitHub repository, so getting the code is one command. git clone into the directory of your choice, then copy the env template. Everything you need, docker-compose.yml, Caddyfile, and .env.example, ships in the repo.

git clone https://github.com/automatiabcn/abs.git
cd abs
cp .env.example .env

3. Fill in .env

Open .env and set ABS_LICENSE_KEY (from your welcome email), ABS_PUBLIC_HOSTNAME (the domain you pointed at the server), and ABS_ACME_EMAIL (used by Let's Encrypt). Provider API keys are optional, paste only the ones you plan to use (Anthropic, OpenAI, Groq, Cohere). You can also leave them empty and add them later via the admin UI.

nano .env
# Required:
#   ABS_LICENSE_KEY=...        (from your welcome email, sent within 24h)
#   ABS_PUBLIC_HOSTNAME=abs.yourdomain.com
#   ABS_ACME_EMAIL=you@yourdomain.com
# Optional provider keys (only the ones you plan to use):
#   ANTHROPIC_API_KEY=sk-ant-...
#   OPENAI_API_KEY=sk-...
#   GROQ_API_KEY=gsk_...
#   COHERE_API_KEY=...

4. Bring ABS up

SetupGuide.section4Body

docker compose up -d
docker compose ps          # backend should be "healthy" in ~30s
curl https://abs.yourdomain.com/healthz   # → {"ok":true}

5. First-run admin onboarding

Open https://abs.yourdomain.com/setup in your browser. The wizard walks you through admin email + password, an optional vault key for at-rest encryption, confirming the provider keys you set in .env, and a final license JWT validation against our activation worker. You're done, start chatting with your private ABS.

# Open in your browser:
# https://abs.yourdomain.com/setup
# Wizard:
#   1. Admin email + password
#   2. Optional vault key
#   3. Confirm provider keys (already in .env)
#   4. License JWT validation

Troubleshooting

Most setup hiccups come down to DNS, the firewall, or a typo in your license key. Here are the quickest fixes for the issues we see most often.

License activation fails

If docker compose logs backend shows license invalid or license unreachable, double-check ABS_LICENSE_KEY in .env (no quotes, no spaces) and confirm the backend can reach our activation worker. A fresh git pull also picks up any backend fixes since the repo is public.

cd abs && git pull origin main
# License activation fails?
curl -I https://abs-license-activation.automatiaabs.workers.dev
docker compose logs backend | tail -50 | grep -i license

Clock skew rejecting the license

JWT validation is strict on time. If the host clock is off by more than ~30 seconds, activation will fail. Enable NTP with sudo timedatectl set-ntp true and re-run docker compose up -d.

sudo timedatectl set-ntp true
sudo timedatectl status        # ensure clock is in sync
curl -I https://abs-license-activation.automatiaabs.workers.dev

Caddy can't get a certificate

If https://abs.yourdomain.com doesn't load, check that your DNS A record points to the server (dig +short abs.yourdomain.com) and that ports 80 and 443 are open in ufw. Caddy logs (docker compose logs caddy) will tell you exactly what Let's Encrypt rejected.

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

Backend running out of memory

On a 2 GB host you may hit OOM on first boot when models warm up. Check docker stats and free -h. The fix is either bumping the VPS to 4 GB (CX22 default), or trimming the local model list in the admin UI to just the providers you use.

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

Landing page won't load

If the marketing landing returns 502, the most common cause is a missing ABS_PUBLIC_URL in .env (it should match https://abs.yourdomain.com). Set it, then docker compose restart landing.

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

Stuck? We'll help.

Reply to your welcome email or write to info@automatiabcn.com. Usual response time is under 4 hours during EU business hours.

ABS