Installation and updates

AdManta runs in Docker: the web app, a task worker, PostgreSQL, Redis and nginx start together. The installer takes care of the steps for you.

Please read first. AdManta provides this guide as instructions only. You run the server, so you are responsible for it: installed packages, security updates, firewall, malware protection, backups and all DevOps and cybersecurity work. AdManta accepts no liability for malware, wrongly installed packages, misconfiguration or security incidents on your server. Read every script before you run it, and use the commands as a starting point that works for most setups.

What you need

• A virtual private server (VPS) running Ubuntu 22.04, 24.04 or 26.04, or any host that can run Docker. 2 GB of memory is enough to start, 4 GB is more comfortable.
• A public IPv4 address on the server. This is required. The download site (admanta.io), Docker Hub and other sources are reachable over IPv4 only. A server with only an IPv6 address cannot download anything: curl fails at once and ping 1.1.1.1 gets no answer. Some providers create servers without IPv4 by default (at Hetzner, tick Public IPv4 when you create the server). Check with ip -4 addr show scope global: you need a public address there, not one starting with 10., 172.16 to 172.31, 192.168 or 100.64. An IPv4 address that belongs to another location cannot be attached later, so choose the same location as the server.
• A domain name with an A record pointing at the server's IPv4 address (add an AAAA record only if you also use IPv6). It is needed for HTTPS and for ads to work on other sites. Set the record before you run the installer and check it with dig +short ads.example.com: the output must be your server's IPv4. For a first test you can skip the domain: the installer then uses the server's IP address with a self-signed certificate, so your browser shows a warning once. That is for testing only, and ads on other sites would be blocked.
• Open ports 80 and 443 to the internet, plus 22 for SSH. The installer sets up the firewall, but a firewall at your provider must allow these too. Port 80 is needed for the certificate.
• Root access (or sudo) over SSH. Use an SSH key if you can.
• Your licence key and the e-mail address you bought with. The first download activates the licence.

Nothing else. Docker is installed in the next step.

Quick check before you start, run on the server:

curl -4 -sI https://example.com | head -1   # must print HTTP/2 200 or similar
dig +short ads.example.com                   # must print this server's IPv4

Step 1: Install Docker on your VPS

Skip this step if your host already runs Docker, for example a managed container platform.

On a VPS, connect with SSH and run:

sudo apt-get update && sudo apt-get upgrade -y
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

This updates the system packages and installs Docker from Docker's official script, including the docker compose plugin that AdManta needs. Check it worked:

sudo docker --version
sudo docker compose version

Docker's official install guide is at docs.docker.com/engine/install/ubuntu. Some older guides use apt-key and Docker Compose 1.x. Both are outdated, so use the commands above or Docker's guide instead.

Step 2: Install AdManta

The one-command way (recommended)

The installer asks for the e-mail and licence key from your purchase, downloads the newest AdManta release that belongs to your licence, and starts the setup. Download the script first, so you can read it, then run it:

curl -fsSL https://www.admanta.io/install.sh -o admanta-install.sh
sudo bash admanta-install.sh

It does this, in order:

1. Updates the system packages.
2. Asks for your licence e-mail and key and asks the AdManta download service for the newest release. This is the same check as the download page. The first download activates your licence. Your 12 months of updates run from the purchase date.
3. Unpacks AdManta to /opt/adserver.
4. Runs the release's own installer. It asks only for your domain (press Enter to use the server's IP address), checks that the domain points at the server, installs Docker, Caddy (HTTPS) and the firewall if they are missing, writes .env with random secrets, builds and starts AdManta, and stores your licence key so the panel can look for updates by itself.

At the end the installer tells you to open https://your-domain/setup/. Enter your licence key (the one you installed with), an e-mail address and a password. The key is checked against the one stored on your server, so no mail and no internet connection is needed. The e-mail address becomes your login. After the first account exists the page closes for good.

The installer did not get a licence key? Use the setup token instead: open the Use the setup token instead section on the same page, or open the link https://your-domain/setup/#... that the installer printed. The link is also saved in /opt/adserver/SETUP_LINK.txt (readable by root only). To print it again before you used it, run docker compose exec web python manage.py setup_link in /opt/adserver.

To skip the questions, or to create the admin directly without the setup link, pass options:

sudo bash admanta-install.sh --license-email you@example.com --license-key ADMA-XXXX-XXXX-XXXX-XXXX \
  --domain ads.example.com --email you@example.com --password 'a-long-password'

Use the ADMANTA_LICENSE_KEY environment variable instead of --license-key if other people can see your process list.

The manual way

Download the release zip from the download page (https://www.admanta.io/download), upload it to the server and run the installer in it:

scp admanta-1.0.0.zip your-user@your-server-ip:~
ssh your-user@your-server-ip
sudo apt-get install -y unzip
sudo mkdir -p /opt/adserver
sudo unzip ~/admanta-1.0.0.zip -d /opt/adserver
cd /opt/adserver
sudo bash install.sh

You can run the installer again at any time. It never overwrites an existing .env and keeps an existing admin user.

SSH safety. The installer only switches to key-only SSH login when an SSH key is available, either with --ssh-key or already in your ~/.ssh/authorized_keys. Without a key it leaves SSH settings alone, so you cannot lock yourself out.

Step 3: Sign in and secure the account

Open https://your-domain/setup/ and create your account with your licence key (or with the setup token). Then sign in, open Account security and switch on two-factor authentication.

If you used the one-command way or --license-key, your licence key is already stored and the panel shows your update status under Licence & updates. Otherwise enter the key there yourself.

Optionally set up e-mail under Settings, E-mail (the SMTP password is stored encrypted). Without e-mail the login page shows the changepassword command instead of "Forgot password".

Next: create your first ad.

Your configuration

The installer writes everything to /opt/adserver/.env (readable only by root). Back this file up and never share it. You can change optional values later and restart with docker compose up -d.

Installing by hand

Use this route for a custom setup. The installer does exactly these steps.

sudo bash deploy/setup-vps.sh                    # Docker, Caddy, firewall, hardening
cp .env.example .env && nano .env                # SECRET_KEY, passwords, domain, ADMIN_URL
sudo cp deploy/Caddyfile /etc/caddy/Caddyfile    # replace YOUR_DOMAIN, then: sudo systemctl reload caddy
docker compose up -d --build
docker compose exec web python manage.py createsuperuser

Generate secrets with openssl rand -hex 32. The database password must match in POSTGRES_PASSWORD and DATABASE_URL, and the Redis password in REDIS_PASSWORD, REDIS_URL, CELERY_BROKER_URL and CELERY_RESULT_BACKEND. With DEBUG=False an ADMIN_URL other than admin/ is required.

Try it on your own computer first

You can test without a domain. In .env set DEBUG=True and ADMIN_URL=admin/, then run:

docker compose up -d --build
docker compose exec web python manage.py createsuperuser

Open http://localhost:8000/panel/.

Updating

Updates come as a zip that the panel downloads and verifies for you.

1. The installer already creates the folder the panel saves updates to (updates). If you installed by hand, create it once:

mkdir -p updates && sudo chown 1000:1000 updates

2. In the panel, open Licence & updates and press Download update. The panel checks daily and shows a badge when a new version is available.
3. On the server, in the install folder, run:

./update.sh

The script backs up the database and the code into backups/, replaces the code, rebuilds, and waits until /health/ answers. If the app does not become healthy, it restores code and database automatically.

Your .env, media/, backups/, updates/, staticfiles/ and docker-compose.override.yml stay untouched. Everything else is replaced by the update, so do not edit release files. Configure through .env and the panel. The update checks the digital signature of the package before it touches anything.

Backups

Run the backup script every night from cron:

0 3 * * * cd /opt/adserver && ./scripts/backup.sh >> backups/backup.log 2>&1

To restore, the header of scripts/backup.sh lists the two commands. Test a restore once on a spare machine before you rely on it.

Everyday commands

docker compose logs -f web        # application and access log
docker compose ps                 # health of every container
docker compose restart web        # restart only the web container
docker compose exec web python manage.py shell

Other platforms

AdManta also runs on any container host (Fly.io, Render, Railway and similar). The container needs DATABASE_URL, REDIS_URL and the variables from .env.example, a persistent volume at /app/media, and a proxy that sets X-Forwarded-For and X-Forwarded-Proto. Keep the task worker running with celery -A adserver worker and celery -A adserver beat.

Troubleshooting