fix: docs pages, navbar, footer updates from QA sprint

This commit is contained in:
Krystie
2026-08-12 17:34:14 -07:00
parent a3648f66d8
commit ee4066f19c
6 changed files with 1178 additions and 200 deletions
+345 -55
View File
@@ -10,90 +10,380 @@ export default function DocsInstallationPage() {
title="Installation Guide"
intro="DashCaddy ships as a Docker-based deployment with a guided installer that handles dependency checks, configuration generation, and first launch. This guide covers prerequisites, the installer flow, and what to expect on first run."
>
<h2>Prerequisites</h2>
<p>Before installing, make sure the host has the following:</p>
<ul>
<li><strong>Docker</strong> and <strong>Docker Compose</strong> the runtime foundation for all DashCaddy services.</li>
<li><strong>Node.js 20+</strong> required for the DashCaddy API server.</li>
<li><strong>Caddy</strong> with Admin API access enabled the reverse proxy and HTTPS layer.</li>
<li><strong>Technitium DNS</strong> optional, but recommended for automatic DNS record management.</li>
<li>A static host or stable IP if you plan to expose services beyond the local network.</li>
</ul>
<h2>System requirements</h2>
<p>Before installing DashCaddy, verify that your host meets these minimum requirements:</p>
<div className="overflow-x-auto">
<table className="w-full text-left text-sm">
<thead>
<tr className="border-b border-surface-700">
<th className="py-3 pr-4 font-semibold text-surface-200">Component</th>
<th className="py-3 pr-4 font-semibold text-surface-200">Minimum</th>
<th className="py-3 font-semibold text-surface-200">Recommended</th>
</tr>
</thead>
<tbody className="text-surface-300">
<tr className="border-b border-surface-800">
<td className="py-3 pr-4">Operating System</td>
<td className="py-3 pr-4">Linux (Ubuntu 20.04+, Debian 11+, CentOS 8+)</td>
<td className="py-3">Ubuntu 22.04 LTS or Debian 12</td>
</tr>
<tr className="border-b border-surface-800">
<td className="py-3 pr-4">CPU</td>
<td className="py-3 pr-4">2 cores</td>
<td className="py-3">4+ cores</td>
</tr>
<tr className="border-b border-surface-800">
<td className="py-3 pr-4">RAM</td>
<td className="py-3 pr-4">2 GB</td>
<td className="py-3">4+ GB (8 GB for 20+ services)</td>
</tr>
<tr className="border-b border-surface-800">
<td className="py-3 pr-4">Disk</td>
<td className="py-3 pr-4">10 GB free</td>
<td className="py-3">50+ GB SSD</td>
</tr>
<tr className="border-b border-surface-800">
<td className="py-3 pr-4">Docker</td>
<td className="py-3 pr-4">20.10+</td>
<td className="py-3">Latest stable</td>
</tr>
<tr className="border-b border-surface-800">
<td className="py-3 pr-4">Docker Compose</td>
<td className="py-3 pr-4">v2.0+</td>
<td className="py-3">Latest stable</td>
</tr>
<tr className="border-b border-surface-800">
<td className="py-3 pr-4">Node.js</td>
<td className="py-3 pr-4">20.x LTS</td>
<td className="py-3">20.x LTS or 22.x LTS</td>
</tr>
<tr className="border-b border-surface-800">
<td className="py-3 pr-4">Caddy</td>
<td className="py-3 pr-4">2.6+ with Admin API</td>
<td className="py-3">Latest stable</td>
</tr>
<tr>
<td className="py-3 pr-4">Technitium DNS</td>
<td className="py-3 pr-4">Optional</td>
<td className="py-3">Latest stable (for auto DNS)</td>
</tr>
</tbody>
</table>
</div>
<blockquote className="border-l-4 border-brand-500/50 bg-brand-500/5 p-4 rounded-r-lg mt-6">
<p className="text-surface-300">
<strong className="text-brand-400">Note:</strong> DashCaddy can run on Windows and macOS for development, but production deployments should target Linux. Docker Desktop works for testing but is not recommended for production workloads.
</p>
</blockquote>
<h2>Quick start with start.sh</h2>
<p>
The fastest path to a running DashCaddy is the bundled <code>start.sh</code> script. It performs environment
checks, pulls the required containers, generates configuration, and brings the stack up.
checks, pulls the required containers, generates configuration, and brings the stack up in a single command.
</p>
<pre className="mt-4 overflow-x-auto rounded-lg border border-surface-700/50 bg-surface-950/80 p-4 text-sm"><code>{`# Clone the repository
git clone https://github.com/samiahmed7777/dashcaddy.git
cd dashcaddy
# Make the launcher executable and run it
chmod +x start.sh
./start.sh`}</code></pre>
<h3>Step 1: Clone the repository</h3>
<pre className="mt-4 overflow-x-auto rounded-lg border border-surface-700/50 bg-surface-950/80 p-4 text-sm"><code>{`git clone https://github.com/samiahmed7777/dashcaddy.git
cd dashcaddy`}</code></pre>
<h3>Step 2: Make the launcher executable</h3>
<pre className="mt-4 overflow-x-auto rounded-lg border border-surface-700/50 bg-surface-950/80 p-4 text-sm"><code>{`chmod +x start.sh`}</code></pre>
<h3>Step 3: Run the installer</h3>
<pre className="mt-4 overflow-x-auto rounded-lg border border-surface-700/50 bg-surface-950/80 p-4 text-sm"><code>{`./start.sh`}</code></pre>
<p>
The script is idempotent re-running it will reconcile the stack rather than clobber an existing install.
If DashCaddy is already running, <code>start.sh</code> detects this and offers to update configuration or
restart services instead of reinstalling from scratch.
</p>
<h2>The guided installer</h2>
<p>
For users who prefer a walk-through, DashCaddy includes a dedicated installer that steps through:
</p>
<h3>What start.sh does</h3>
<p>Under the hood, the script performs these steps:</p>
<ol>
<li><strong>Dependency checks</strong> verifies Docker, Node.js, and Caddy are present and reachable.</li>
<li><strong>Path selection</strong> chooses where state, configs, and certificates are stored.</li>
<li><strong>Configuration generation</strong> writes environment files and Caddy/DNS integration settings.</li>
<li><strong>Container deployment</strong> pulls images and starts the API, dashboard, and supporting services.</li>
<li><strong>First-launch validation</strong> confirms the API responds and the dashboard loads.</li>
<li><strong>Dependency validation</strong> checks for Docker, Docker Compose, Node.js, and Caddy</li>
<li><strong>Port availability check</strong> verifies ports 80, 443, and 2019 (Caddy Admin API) are free</li>
<li><strong>Configuration generation</strong> creates <code>.env</code> file with sensible defaults</li>
<li><strong>Docker image pull</strong> fetches the DashCaddy API and dashboard images</li>
<li><strong>Container startup</strong> launches the stack via Docker Compose</li>
<li><strong>Health check</strong> waits for the API to respond on <code>/healthz</code></li>
<li><strong>Dashboard URL display</strong> prints the access URL and initial admin credentials</li>
</ol>
<h2>First launch &amp; the Smart Defaults Wizard</h2>
<h2>Docker Compose configuration</h2>
<p>
On first launch the dashboard opens to the <strong>Smart Defaults Wizard</strong>. It surveys your host and
pre-fills sensible choices so you can go from install to a working deployment in minutes:
If you prefer to inspect or customize the Docker Compose configuration before launching, here's the
default <code>docker-compose.yml</code> that <code>start.sh</code> generates:
</p>
<pre className="mt-4 overflow-x-auto rounded-lg border border-surface-700/50 bg-surface-950/80 p-4 text-sm"><code>{`version: '3.8'
services:
dashcaddy-api:
image: samiahmed7777/dashcaddy-api:latest
container_name: dashcaddy-api
restart: unless-stopped
ports:
- "3001:3001" # API port
volumes:
- ./data:/app/data
- ./config:/app/config
- /var/run/docker.sock:/var/run/docker.sock:ro
environment:
- NODE_ENV=production
- DASHCADDY_PORT=3001
- CADDY_ADMIN_URL=http://caddy:2019
- TECHNITIUM_API_URL=http://technitium:5380
- TECHNITIUM_API_TOKEN=\${TECHNITIUM_API_TOKEN}
- JWT_SECRET=\${JWT_SECRET}
- DASHCA_ENABLED=true
depends_on:
- caddy
- technitium
networks:
- dashcaddy-net
dashcaddy-dashboard:
image: samiahmed7777/dashcaddy-dashboard:latest
container_name: dashcaddy-dashboard
restart: unless-stopped
ports:
- "3000:3000" # Dashboard port
environment:
- NEXT_PUBLIC_API_URL=http://localhost:3001
depends_on:
- dashcaddy-api
networks:
- dashcaddy-net
caddy:
image: caddy:2-alpine
container_name: caddy
restart: unless-stopped
ports:
- "80:80"
- "443:443"
- "2019:2019" # Admin API
volumes:
- ./caddy/Caddyfile:/etc/caddy/Caddyfile
- ./caddy/data:/data
- ./caddy/config:/config
networks:
- dashcaddy-net
technitium:
image: technitium/dns-server:latest
container_name: technitium
restart: unless-stopped
ports:
- "5380:5380" # Web console
- "53:53/udp"
- "53:53/tcp"
volumes:
- ./technitium:/etc/dns
environment:
- DNS_SERVER_DOMAIN=local
networks:
- dashcaddy-net
networks:
dashcaddy-net:
driver: bridge`}</code></pre>
<h2>Environment variables reference</h2>
<p>
DashCaddy's behavior is controlled through environment variables in the <code>.env</code> file. Here's
a complete reference:
</p>
<div className="overflow-x-auto">
<table className="w-full text-left text-sm">
<thead>
<tr className="border-b border-surface-700">
<th className="py-3 pr-4 font-semibold text-surface-200">Variable</th>
<th className="py-3 pr-4 font-semibold text-surface-200">Default</th>
<th className="py-3 font-semibold text-surface-200">Description</th>
</tr>
</thead>
<tbody className="text-surface-300">
<tr className="border-b border-surface-800">
<td className="py-3 pr-4 font-mono text-xs">NODE_ENV</td>
<td className="py-3 pr-4">production</td>
<td className="py-3">Runtime environment (development or production)</td>
</tr>
<tr className="border-b border-surface-800">
<td className="py-3 pr-4 font-mono text-xs">DASHCADDY_PORT</td>
<td className="py-3 pr-4">3001</td>
<td className="py-3">Port for the DashCaddy API server</td>
</tr>
<tr className="border-b border-surface-800">
<td className="py-3 pr-4 font-mono text-xs">CADDY_ADMIN_URL</td>
<td className="py-3 pr-4">http://caddy:2019</td>
<td className="py-3">Caddy Admin API endpoint</td>
</tr>
<tr className="border-b border-surface-800">
<td className="py-3 pr-4 font-mono text-xs">TECHNITIUM_API_URL</td>
<td className="py-3 pr-4">http://technitium:5380</td>
<td className="py-3">Technitium DNS API endpoint</td>
</tr>
<tr className="border-b border-surface-800">
<td className="py-3 pr-4 font-mono text-xs">TECHNITIUM_API_TOKEN</td>
<td className="py-3 pr-4">(required)</td>
<td className="py-3">API token for Technitium DNS authentication</td>
</tr>
<tr className="border-b border-surface-800">
<td className="py-3 pr-4 font-mono text-xs">JWT_SECRET</td>
<td className="py-3 pr-4">(auto-generated)</td>
<td className="py-3">Secret key for JWT token signing</td>
</tr>
<tr className="border-b border-surface-800">
<td className="py-3 pr-4 font-mono text-xs">DASHCA_ENABLED</td>
<td className="py-3 pr-4">true</td>
<td className="py-3">Enable internal certificate authority</td>
</tr>
<tr className="border-b border-surface-800">
<td className="py-3 pr-4 font-mono text-xs">BASE_DOMAIN</td>
<td className="py-3 pr-4">local</td>
<td className="py-3">Base domain for service hostnames</td>
</tr>
<tr className="border-b border-surface-800">
<td className="py-3 pr-4 font-mono text-xs">PROMETHEUS_ENABLED</td>
<td className="py-3 pr-4">true</td>
<td className="py-3">Expose Prometheus metrics at /metrics</td>
</tr>
<tr className="border-b border-surface-800">
<td className="py-3 pr-4 font-mono text-xs">LOG_LEVEL</td>
<td className="py-3 pr-4">info</td>
<td className="py-3">Logging verbosity (debug, info, warn, error)</td>
</tr>
<tr>
<td className="py-3 pr-4 font-mono text-xs">DATA_DIR</td>
<td className="py-3 pr-4">./data</td>
<td className="py-3">Path for persistent state storage</td>
</tr>
</tbody>
</table>
</div>
<h2>The Smart Defaults Wizard</h2>
<blockquote className="border-l-4 border-brand-500/50 bg-brand-500/5 p-4 rounded-r-lg">
<p className="text-surface-300">
<strong className="text-brand-400">Smart Defaults Wizard:</strong> On first launch, the dashboard opens to the Smart Defaults Wizard. It surveys your host and pre-fills sensible choices so you can go from install to a working deployment in minutes. Every default is editable — the wizard simply gives you a known-good starting point instead of a blank slate.
</p>
</blockquote>
<p>The wizard performs these tasks automatically:</p>
<ul>
<li>Detects the Caddy Admin API endpoint and validates connectivity.</li>
<li>Detects Technitium DNS (if installed) and configures the API token and zone.</li>
<li>Proposes a base domain and naming convention for new services.</li>
<li>Initializes the internal certificate authority (DashCA) and offers the root certificate for download.</li>
<li>Creates the initial admin account and offers TOTP 2FA enrollment.</li>
<li><strong>Caddy detection</strong> — detects the Caddy Admin API endpoint and validates connectivity</li>
<li><strong>Technitium detection</strong> — detects Technitium DNS (if installed) and configures the API token and zone</li>
<li><strong>Domain suggestion</strong> — proposes a base domain and naming convention for new services</li>
<li><strong>DashCA initialization</strong> — initializes the internal certificate authority and offers the root certificate for download</li>
<li><strong>Admin account creation</strong> — creates the initial admin account and offers TOTP 2FA enrollment</li>
<li><strong>Network scanning</strong> — scans for existing Docker containers and offers to adopt them via Service Discovery</li>
</ul>
<p>
Every default is editable the wizard simply gives you a known-good starting point instead of a blank slate.
</p>
<h2>Manual setup</h2>
<p>
If you want direct control over paths, services, Caddy, and DNS integration, you can deploy manually:
If you want direct control over paths, services, Caddy, and DNS integration, you can deploy manually
instead of using <code>start.sh</code>:
</p>
<ol>
<li>Clone the repository.</li>
<li>Install the API dependencies (<code>npm ci</code>).</li>
<li>Prepare Caddy and confirm the Admin API is reachable.</li>
<li>Prepare Technitium DNS if you want automatic DNS changes.</li>
<li>Configure environment variables and state paths.</li>
<li>Start the DashCaddy API (<code>npm run start</code> or via your process manager).</li>
<li>Serve the dashboard through Caddy.</li>
<li>Clone the repository: <code>git clone https://github.com/samiahmed7777/dashcaddy.git</code></li>
<li>Install the API dependencies: <code>cd dashcaddy && npm ci</code></li>
<li>Prepare Caddy and confirm the Admin API is reachable on port 2019</li>
<li>Prepare Technitium DNS if you want automatic DNS changes (optional)</li>
<li>Copy <code>.env.example</code> to <code>.env</code> and configure environment variables</li>
<li>Start the DashCaddy API: <code>npm run start</code> (or use your process manager like systemd or PM2)</li>
<li>Serve the dashboard through Caddy by adding a reverse proxy rule to your Caddyfile</li>
</ol>
<h2>Post-install checks</h2>
<p>After the stack is up, verify each layer:</p>
<ul>
<li>The dashboard loads in your browser.</li>
<li>The API responds check <code>/healthz</code> and <code>/readyz</code>.</li>
<li>The Caddy Admin API is reachable from the API server.</li>
<li>The service management UI loads and lists the host&apos;s containers.</li>
<li>DNS and certificate integration report healthy (if configured).</li>
<li>Prometheus metrics are exposed at <code>/metrics</code> (if scraping is enabled).</li>
</ul>
<h2>Common installation issues</h2>
<p>If you encounter problems during installation, check this troubleshooting table:</p>
<div className="overflow-x-auto">
<table className="w-full text-left text-sm">
<thead>
<tr className="border-b border-surface-700">
<th className="py-3 pr-4 font-semibold text-surface-200">Symptom</th>
<th className="py-3 pr-4 font-semibold text-surface-200">Cause</th>
<th className="py-3 font-semibold text-surface-200">Solution</th>
</tr>
</thead>
<tbody className="text-surface-300">
<tr className="border-b border-surface-800">
<td className="py-3 pr-4">Port 80 or 443 already in use</td>
<td className="py-3 pr-4">Another web server (nginx, Apache) is running</td>
<td className="py-3">Stop the conflicting service or change Caddy's ports in docker-compose.yml</td>
</tr>
<tr className="border-b border-surface-800">
<td className="py-3 pr-4">Docker permission denied</td>
<td className="py-3 pr-4">Current user not in docker group</td>
<td className="py-3">Run <code>sudo usermod -aG docker $USER</code> and log out/in</td>
</tr>
<tr className="border-b border-surface-800">
<td className="py-3 pr-4">Caddy Admin API unreachable</td>
<td className="py-3 pr-4">Caddy not running or Admin API disabled</td>
<td className="py-3">Ensure Caddy is running with <code>admin :2019</code> in its config</td>
</tr>
<tr className="border-b border-surface-800">
<td className="py-3 pr-4">Technitium API token invalid</td>
<td className="py-3 pr-4">Token not set or expired</td>
<td className="py-3">Generate a new token in Technitium web console and update .env</td>
</tr>
<tr className="border-b border-surface-800">
<td className="py-3 pr-4">Dashboard shows 502 Bad Gateway</td>
<td className="py-3 pr-4">API server not responding</td>
<td className="py-3">Check <code>docker logs dashcaddy-api</code> for errors</td>
</tr>
<tr className="border-b border-surface-800">
<td className="py-3 pr-4">Out of memory during deployment</td>
<td className="py-3 pr-4">Insufficient RAM for container workloads</td>
<td className="py-3">Increase host RAM or reduce concurrent service deployments</td>
</tr>
<tr>
<td className="py-3 pr-4">Certificate trust errors in browser</td>
<td className="py-3 pr-4">DashCA root cert not installed on client</td>
<td className="py-3">Download root cert from DashCA page and install on client device</td>
</tr>
</tbody>
</table>
</div>
<h2>Post-install verification</h2>
<p>After the stack is up, verify each layer with these commands:</p>
<h3>1. Check container status</h3>
<pre className="mt-4 overflow-x-auto rounded-lg border border-surface-700/50 bg-surface-950/80 p-4 text-sm"><code>{`docker ps --filter "name=dashcaddy"
# Expected: dashcaddy-api, dashcaddy-dashboard, caddy, technitium all running`}</code></pre>
<h3>2. Verify API health</h3>
<pre className="mt-4 overflow-x-auto rounded-lg border border-surface-700/50 bg-surface-950/80 p-4 text-sm"><code>{`curl http://localhost:3001/healthz
# Expected: {"status":"ok","version":"1.0.0"}
curl http://localhost:3001/readyz
# Expected: {"status":"ready","checks":{"caddy":true,"technitium":true}}`}</code></pre>
<h3>3. Test Caddy Admin API</h3>
<pre className="mt-4 overflow-x-auto rounded-lg border border-surface-700/50 bg-surface-950/80 p-4 text-sm"><code>{`curl http://localhost:2019/config/
# Expected: JSON configuration object`}</code></pre>
<h3>4. Verify Technitium DNS</h3>
<pre className="mt-4 overflow-x-auto rounded-lg border border-surface-700/50 bg-surface-950/80 p-4 text-sm"><code>{`curl http://localhost:5380/api/dns/zones/list?token=YOUR_TOKEN
# Expected: List of DNS zones`}</code></pre>
<h3>5. Check Prometheus metrics</h3>
<pre className="mt-4 overflow-x-auto rounded-lg border border-surface-700/50 bg-surface-950/80 p-4 text-sm"><code>{`curl http://localhost:3001/metrics
# Expected: Prometheus-formatted metrics output`}</code></pre>
<h3>6. Access the dashboard</h3>
<p>Open your browser and navigate to <code>http://localhost:3000</code> (or your configured domain). You should see the DashCaddy dashboard login screen.</p>
<h2>Next steps</h2>
<p>
Once install checks pass, head to the <a href="/docs/first-service">Deploy Your First Service</a> guide to
Once install checks pass, head to the <a href="/docs/first-service" className="text-brand-400 hover:text-brand-300 underline">Deploy Your First Service</a> guide to
bring your first application online.
</p>
<p>
If you need to understand the architecture in more depth, see the <a href="/docs/overview" className="text-brand-400 hover:text-brand-300 underline">Product Overview</a>.
</p>
</DocsLayout>
<Footer />
</div>