Installation

import { Steps } from ‘@astrojs/starlight/components’;

Nexus installs from a single shell script that handles everything — Docker, Caddy, secrets, the database, and the application container. A typical install takes 5–10 minutes depending on your server’s internet connection speed.

Before you begin

• A fresh Ubuntu 22.04, 24.04, or 26.04 server with root access
• A domain name (or subdomain) with an A record already pointing at your server’s IP. The Let’s Encrypt certificate request happens during install — if DNS isn’t resolving first, the install will fail at the Caddy step.
• Ports 80 and 443 open on your server’s firewall

Running the installer

The installer must be downloaded first and run directly — it will not run when piped through curl. This is intentional.

1. Download the install script

   curl -fsSL https://raw.githubusercontent.com/ResofireV2/nexus/master/install.sh -o install.sh

2. Run it as root

   bash install.sh

3. Answer the prompts

   The installer asks three questions before doing anything:

   • Domain — the full hostname where Nexus will be served, e.g. forum.example.com. Enter exactly what your A record points to.
   • Email for SSL certificate — used by Let’s Encrypt for certificate renewal notices. Not stored anywhere else.
   • Include www redirect? — only shown if you entered an apex domain (e.g. example.com). Not shown for subdomains, since www.forum.example.com is not meaningful.

4. Wait for the build to complete

   After the prompts, the installer runs without further input. It will:

   • Install Docker CE and Caddy from their official apt repositories (skipped if already installed)
   • Create persistent data directories at /opt/nexus-data
   • Download the latest tagged release from GitHub
   • Extract and place it at /opt/nexus
   • Generate all secrets (SECRET_KEY_BASE, JWT_SECRET, SESSION_SIGNING_SALT, DB_PASSWORD) and write them to /opt/nexus/.env
   • Write the Caddyfile to /opt/nexus/Caddyfile and copy it to /etc/caddy/Caddyfile
   • Build and launch the Docker containers with docker compose -f docker-compose.prod.yml up -d --build
   • Wait for the application to report Running NexusWeb.Endpoint in its logs
   • Install nexus-update and nexus-backup to /usr/local/bin

   The build step — compiling Elixir, building assets — typically takes 5–10 minutes on a fresh server.

5. Confirm it’s running

   When the installer finishes you’ll see:

   ✓ Nexus is live!
   
     URL:      https://your-domain.com
     App code: /opt/nexus
     Data:     /opt/nexus-data

   Open https://your-domain.com in a browser. You’ll be taken to the first-time setup screen to create your admin account.

What gets installed where

Path	Contents
/opt/nexus	Application code, Caddyfile, .env
/opt/nexus/.env	All secrets and configuration (mode 600, root only)
/opt/nexus/Caddyfile	Canonical Caddyfile — edit this, not /etc/caddy/Caddyfile
/opt/nexus-data/postgres	PostgreSQL data volume
/opt/nexus-data/uploads	User-uploaded files (avatars, post images, covers, logos)
/usr/local/bin/nexus-update	Management script for applying updates
/usr/local/bin/nexus-backup	Management script for snapshotting database and uploads

If something goes wrong

DNS not resolving yet — Caddy will fail to obtain a TLS certificate. Make sure your A record is in place and resolving before running the installer. Run nslookup your-domain.com from any machine to confirm.

Port 80 or 443 blocked — Let’s Encrypt needs to reach port 80 on your server to complete the HTTP challenge. Check your VPS firewall rules (UFW, iptables, or your provider’s cloud firewall).

Build takes longer than expected — The Docker build compiles Elixir from source inside the container. On a 1 vCPU server this can take 15+ minutes. This only happens on first install and after version upgrades — normal container restarts are fast.

Check the logs — If Nexus starts but immediately exits, check the application logs:

docker compose -f /opt/nexus/docker-compose.prod.yml logs app