Installation Guide

Before you start

You only need three things to install DashCaddy:

• A Linux host that stays on — Ubuntu 22.04 LTS, Debian 12, or any recent Linux distribution. 2 GB RAM and a few GB of disk are enough to start.
• Root or sudo access — the installer writes to /etc/dashcaddy, /opt/dockerdata, and the system Docker daemon.
• A hostname — a domain you own, a custom-TLD like dashcaddy.home, or just your machine's IP for local-only use.

Pick your hostname

DashCaddy uses a single base hostname and creates subdomains under it for every service you add (for example plex.dashcaddy.home, homeassistant.dashcaddy.home). Choose the option that matches your situation:

Option A — A real domain you own (recommended)

If you own example.com, register dashcaddy.example.comas a DNS A record pointing at your host's public IP. You can buy a domain for about $10/year from any registrar (Namecheap, Cloudflare, Porkbun, Google Domains). With a real domain, DashCaddy automatically gets a trusted Let's Encrypt certificate on first launch — no certificate warnings, no client setup.

Option B — A custom TLD on your home network

Use a domain like dashcaddy.home, dashcaddy.lan, or dashcaddy.local. These will not resolve on the public internet, which is exactly what you want for a home server. Two ways to make them resolve:

• Router DNS — most home routers let you add a local DNS entry. Point *.dashcaddy.home at your server's LAN IP. All devices on your network pick it up automatically.
• Tailscale MagicDNS — install Tailscale on the host and your devices. Their MagicDNS gives every machine a stable name.tailnet.ts.net name, no DNS editing needed.

Custom TLDs require installing DashCaddy's internal CA certificate (DashCA) on each device that connects. The setup wizard walks you through this on first run.

Option C — A direct IP address

If you don't want to set up DNS at all, you can reach DashCaddy at https://192.168.x.x:port. This works for a single machine on a LAN, but the URL changes when the host gets a new IP and you lose subdomain support. Useful for a quick test, not a permanent setup.

No port forwarding?If your ISP puts you behind CGNAT or you don't want to open ports 80 and 443, DashCaddy works fine behind a Tailscale tunnel or Cloudflare Tunnel. Set up the tunnel first, point your hostname at the tunnel's origin, then run the installer with --no-caddy and let the tunnel handle HTTPS termination.

Run the installer

Open a terminal on the host you want to install DashCaddy on and run one of these:

Three-command install (most users)

# 1. Download and run the installer
curl -fsSL https://get.dashcaddy.net | bash

# 2. Answer the prompts (domain, install location, storage size)
#    Defaults are sensible — just press Enter to accept.

# 3. Open the URL the installer prints at the end

Two-keystroke install (no typing)

# Install with a public domain — only thing you type is the domain
curl -fsSL https://get.dashcaddy.net | bash -s -- --domain dashcaddy.example.com

# Or use a custom TLD (your router / Tailscale handles DNS)
curl -fsSL https://get.dashcaddy.net | bash -s -- --domain dashcaddy.home

# Or skip DNS entirely and use a local address (good for a first test)
curl -fsSL https://get.dashcaddy.net | bash -s -- quick

What the installer does

The installer is a single shell script that runs in seven steps, all idempotent — re-running it on an existing install reconciles the stack rather than clobbering your config:

1. Detect your environment — operating system, package manager, free disk space, available memory, public and LAN IP addresses
2. Install prerequisites — Docker Engine and the Docker Compose plugin if missing
3. Write configuration — generates /etc/dashcaddy/, /opt/dockerdata/, and the DashCaddy config file with sensible defaults
4. Pull the DashCaddy container image — fetches the latest release from the public registry
5. Start the DashCaddy container — launches dashcaddy-api on port 3001, mounts persistent data volumes
6. Health check — waits for the API to respond on /healthz before continuing
7. Print the access URL — shows the dashboard address and any follow-up commands

If the installer ever hits a problem, it stops at the step that failed and tells you exactly which command to re-run to retry. It does not silently leave a half-installed state behind.

The first-run setup wizard

When you open the dashboard URL the installer printed, you land on the setup wizard. It runs once and writes your configuration to disk — every choice is editable later from the settings page.

The wizard walks through these screens:

1. Pick a configuration profile — Professional Home Lab (recommended for most users), Simple (minimal config), or Public (for VPS deployments exposed to the internet)
2. Configure your network — your domain, the LAN IP that'll be used for service routing, and whether you want to use Tailscale for remote access
3. Set storage limits — max disk usage for Docker data and how much headroom to keep free
4. Review your choices — a summary screen with the resolved values so you can sanity-check before saving
5. Disk-safety confirmation — confirms you understand that bound storage will be created and what happens on uninstall

After the wizard saves, you're asked to create the first admin account. Pick a strong password — this account controls every service DashCaddy manages.

Set up two-factor authentication

Right after creating your admin account, the dashboard prompts you to enroll a TOTP authenticator (Google Authenticator, Authy, 1Password, or any RFC 6238 app). Scan the QR code with your phone, enter the 6-digit code to confirm, and store the recovery codes somewhere safe — they are the only way back into your account if you lose your phone.

Don't skip 2FA. DashCaddy can manage DNS records, start and stop containers, and read credentials for the services it deploys. A leaked password without a second factor is a full compromise. A leaked password with 2FA is just a login screen.

Install the DashCA root certificate (custom-TLD installs only)

If you chose Option B (a custom TLD like dashcaddy.home) or Option C (a direct IP), your browser will warn that the certificate is not trusted — because it isn't, to anyone outside your network. DashCaddy ships an internal certificate authority called DashCA so internal hostnames get a real TLS certificate instead of self-signed warnings.

Visit the DashCA page in the dashboard and follow the per-platform instructions:

• macOS — open the downloaded .crt, add it to the System keychain, set it to “Always Trust”
• Windows — double-click the .crt, install to “Trusted Root Certification Authorities”
• Linux — copy to /usr/local/share/ca-certificates/ and run sudo update-ca-certificates
• iOS / Android — download the profile, install it via Settings, then enable full trust for the CA

You need to install the root certificate on every device that connects to your DashCaddy services, not just the server. There's no way around this for custom-TLD installs — TLS is what keeps your traffic private.

Harden the host right after install

DashCaddy protects the services it manages, but it runs on top of a normal Linux box that's still exposed on your network. Spend five minutes on these four steps:

1. Enable the firewall

# UFW (Ubuntu / Debian)
sudo ufw default deny incoming
sudo ufw allow ssh                  # if you SSH in
sudo ufw allow 80/tcp               # HTTP  (Let's Encrypt + redirect)
sudo ufw allow 443/tcp              # HTTPS
sudo ufw enable

# If you put DashCaddy behind a tunnel (Tailscale / Cloudflare), skip 80/443 above
# and only allow the tunnel interface — see your tunnel provider's docs

2. Disable password SSH login

# Edit /etc/ssh/sshd_config and set:
PasswordAuthentication no
PermitRootLogin prohibit-password    # or "no" if you use a sudo user

sudo systemctl restart sshd

3. Turn on automatic security updates

# Debian / Ubuntu
sudo apt install -y unattended-upgrades
sudo dpkg-reconfigure -plow unattended-upgrades    # answer "Yes"

4. Set up backups

All your DashCaddy state — services, config, encrypted credentials, DashCA — lives in /opt/dockerdata and /etc/dashcaddy. Snapshot those two directories somewhere off the host. Any tool works: rsync to a NAS, resticto Backblaze B2, a systemd timer that tars them up nightly. The dashboard's Backup button exports a single JSON file you can store anywhere if you want a no-setup option.

Verify the install

After the wizard finishes and you've logged in, run through this checklist to confirm everything is wired up correctly:

1. Container is running — docker ps should show dashcaddy-api with status Up
2. API is healthy — from the host, curl http://localhost:3001/healthz returns {"status":"alive"} and /readyz returns 200 with all checks passing
3. Dashboard responds — opening the URL the installer printed shows the dashboard, not a browser error
4. TLS works — the address bar shows a padlock with no warnings (a real cert if you used Option A; trusted if you used Option B with DashCA installed)
5. 2FA works — log out and back in with your password + TOTP code
6. Updates work — the dashboard shows the current version in the footer and the update button is enabled

Troubleshooting a fresh install

Uninstall

If you want to remove DashCaddy cleanly, the installer has an uninstall mode that stops the container, removes the systemd unit, and (optionally) deletes the data volumes:

# Remove DashCaddy but keep your config and data (you can reinstall later)
curl -fsSL https://get.dashcaddy.net | bash -s -- --uninstall

# Remove everything including config and data (irreversible)
curl -fsSL https://get.dashcaddy.net | bash -s -- --uninstall --purge

Next steps

With DashCaddy installed and hardened, head to the Deploy Your First Service guide to bring an application online through the App Selector.

If you want to understand the architecture before adding services, see the Product Overview. For problems during or after install, the Troubleshooting page walks each layer bottom-up.