Install on a server

Run on DigitalOcean

The friendliest way to get Astrodock online if you don't already have a server. We'll create a small machine (a "droplet"), point your domain at it, and finish setup in your browser. About ten minutes, most of it waiting for DNS.

You'll need

A DigitalOcean account, a domain name (from any registrar). Rough cost: a suitable droplet is about $12/month. You do not need to SSH in at any point — DigitalOcean asks for an SSH key when creating a droplet, but the install runs itself.

  1. Create a droplet

    In DigitalOcean, choose Create → Droplets:

    • Image: plain Ubuntu 24.04 LTS is fine — the installer installs Docker itself if the machine doesn't have it. Picking the Docker image under the Marketplace tab just makes the first boot a little quicker, since Docker is already there.
    • Size: a Basic plan with at least 2 GB RAM (1 vCPU). Astrodock itself is comfortable in less, but it builds your apps on the box, and 1 GB can run out of memory during a build.
    • Authentication: add your SSH key (recommended over a password).
    • Advanced options → Add Initialization scripts (user data): paste the two lines below. This installs Astrodock while the droplet boots, so you never have to open a terminal at all. 
      #!/bin/sh
ASTRODOCK_SETUP_TOKEN='REPLACE-THIS-WITH-A-LONG-RANDOM-STRING' sh -c "$(curl -fsSL https://raw.githubusercontent.com/astrodock/astrodock/main/scripts/install.sh)"

      Running against private images?

      Add ASTRODOCK_REGISTRY_USER and ASTRODOCK_REGISTRY_TOKEN to the same line. Do not put a separate docker login command above it — on a stock image Docker is not installed yet at that point, so the login fails silently and the install only discovers it minutes later when the pull is refused.

      About that token

      It has been generated in your browser just now and never sent anywhere — this documentation is a static page with nothing behind it. That also means we have no copy of it: keep the snippet until you have finished setup. Substitute a string of your own if you prefer — 16 characters or more, no spaces.

      The token is only used once, to prove the server is yours when you create your administrator account. It stops working the moment you do. Choosing it here is what removes the "SSH in and read the logs" step.

      Lost it before finishing setup? On the droplet, edit ASTRODOCK_SETUP_TOKEN in /opt/astrodock/.env, then run cd /opt/astrodock && docker compose up -d api to pick up the new one.

    Create it, and note the droplet's public IP address.

    Prefer to install by hand?

    Skip the user-data box and follow the SSH steps below instead. Same result — the script is identical, it just runs when you say so rather than at boot.

  2. Point your domain at the droplet

    Decide which domain your apps live under. We'll use apps.example.com as the example — every app becomes <name>.apps.example.com, and the dashboard is admin.apps.example.com.

    The easiest route is to let DigitalOcean manage DNS. In DigitalOcean go to Networking → Domains, add your domain, then create one wildcard record:

    Type: A    Hostname: *.apps    Will direct to: <your droplet IP>

    That single record covers the dashboard and every app. (At your registrar, set the domain's nameservers to DigitalOcean's, or skip DO DNS and add the same wildcard A record at your registrar instead.) Full details and other registrars: Custom domains & DNS.

    Do this now if you can — DNS changes take a few minutes to spread, so starting early means it's usually ready by the time you need it. If you'd rather not, that's fine: the setup wizard shows you this same record and checks it for you.

  3. Connect to the droplet

    ssh root@<your droplet IP>

  4. Install Docker

    Only if you're installing by hand and want it done separately — the installer in the next step does this for you when Docker is missing.

    curl -fsSL https://get.docker.com | sh

    Confirm it's ready:

    docker compose version

  5. Install Astrodock — one line

    curl -fsSL https://get.astrodock.ai | sh

    That is the whole install. It downloads the compose file, generates every secret for you, pulls the prebuilt images, and starts the stack. There is no source code to clone and nothing to build on the droplet, so it finishes in about a minute.

    When it's done it prints the address to open — your droplet's IP.

    Prefer to build from source?

    Clone the repository instead, then run ./scripts/setup.sh and docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build. Same result; it just builds the images on the droplet rather than pulling them.

  6. Finish setup in your browser

    If you used the user-data box when creating the droplet, skip straight past the SSH steps — Astrodock is already installing itself. Give it about two minutes from droplet creation, then come straight here.

    Open http://<your droplet IP>.

    Give it 60–90 seconds, and expect one blank moment

    On a small droplet the first load takes a minute or so: Docker pulls the images, the containers start, Postgres has to accept connections, and the schema is migrated before anything answers. A refused connection in the first minute is the platform still coming up, not a failure.

    There is also a deliberate gap partway through. The install serves a holding page on port 80, and it has to let go of that port so the platform's own web server can take it over. For a few seconds in between, nothing is listening — the holding page says so when it reaches that point. Reload after a minute and the wizard will be there.

    Still nothing after two or three minutes? The install log is at /var/log/cloud-init-output.log, and a failed install replaces the holding page with the reason rather than leaving you at a dead port.

    Astrodock starts up unconfigured and serves a short setup wizard there, which walks you through the rest:

    1. Create your administrator account, using the setup token. If you set one in user-data, that's the one. If you installed by hand without choosing a token, Astrodock generated one and printed it to its log: 
      cd /opt/astrodock && docker compose logs api | grep -A2 'first-run setup'
    2. Set up email (optional). Where alerts go if an app falls over. Nothing signs in by email, so this is safe to skip.
    3. Enter your domain. The wizard shows you the exact DNS record to create, filled in with your server's IP, and a Check DNS button that tells you whether it's live yet — so you find out here rather than after a certificate has failed.
    4. Turn on HTTPS. Give it a contact email and save. Astrodock republishes its routing and hands you the link to your real dashboard.

    From then on your dashboard lives at https://admin.apps.example.com and the IP address stops being the way in. The certificate is issued on your first visit, so that very first load can take a few seconds.

A note on the setup token and instance metadata

Anything you put in user data stays readable from the droplet's metadata service for the life of the droplet. That's fine for the setup token — it is worthless the moment you claim the account. It is not fine for a password, which is why we suggest choosing a token here and picking your password in the browser, rather than seeding ASTRODOCK_ADMIN_PASSWORD (which install.sh also accepts, and which would stay valid forever).

Note also that the wizard runs over plain HTTP, because at that point the server has no domain and so cannot have a certificate. Your password crosses the wire unencrypted during that brief window. If that matters for your threat model, change it from Settings once HTTPS is live.

Would rather not use the browser at all?

Every step of the wizard has a flag. ./scripts/setup.sh --domain apps.example.com --email you@example.com --admin-email you@example.com --admin-password '…' configures the lot up front, and the platform boots straight to a login page. The wizard exists because it can check your DNS for you; it is not the only way in.

Optional: add a firewall

Astrodock publishes exactly two ports, 80 and 443. Its database, object store, control plane and runner are all on an internal Docker network and are not reachable from outside the machine — so a fresh droplet is not sitting there with an exposed database, and a firewall allowing 80/443 changes very little on day one.

It is still worth adding as defence in depth, because it protects you from a future mistake — something else installed later that publishes a port without you noticing. Under Networking → Firewalls, create one allowing inbound SSH (22), HTTP (80) and HTTPS (443), then attach your droplet. Leave outbound on its default allow-all: builds fetch packages, and certificates need Let's Encrypt.

Use the provider firewall, not ufw

Docker inserts its own routing rules ahead of ufw's chains, so a ufw deny on a published port does not actually block it — you get the appearance of protection without the protection. That is also why Astrodock reports on exposure rather than managing it: Settings → Readiness warns you if anything beyond 80/443 ends up published to the internet.

Other beginner-friendly hosts

Prefer somewhere else? The steps are nearly identical on any provider — create an Ubuntu server, point a wildcard DNS record at it, then follow the install and setup steps above. Good options include Hetzner Cloud (very cheap), Linode/Akamai, Vultr, and AWS Lightsail. See Your own server / any VPS for the provider-agnostic version.

What's next