diff --git a/concepts/domains.mdx b/concepts/domains.mdx index fdbaf5d..9e5a61a 100644 --- a/concepts/domains.mdx +++ b/concepts/domains.mdx @@ -35,10 +35,20 @@ On Nixopus Cloud, every app gets a `*.nixopus.ai` subdomain by default. You can ## Self-hosted domains -For [self-hosted](/self-hosting/installation) installations, point your domain's DNS (A record) to your machine's IP address. Nixopus detects the domain and configures the reverse proxy automatically. +For [self-hosted](/self-hosting/installation) installations, point your domain's DNS to your machine's IP address. Nixopus detects the domain and configures the reverse proxy automatically. + +The record type depends on your [IP family configuration](/self-hosting/configuration#ipv6-and-dual-stack): ``` -A app.example.com → your-machine-ip +# IPv4 (default) +A app.example.com → your-ipv4-address + +# IPv6 +AAAA app.example.com → your-ipv6-address + +# Dual-stack (both) +A app.example.com → your-ipv4-address +AAAA app.example.com → your-ipv6-address ``` diff --git a/self-hosting/configuration.mdx b/self-hosting/configuration.mdx index 83e503e..0a583c0 100644 --- a/self-hosting/configuration.mdx +++ b/self-hosting/configuration.mdx @@ -14,7 +14,9 @@ curl -fsSL install.nixopus.com | sudo DOMAIN=panel.example.com ADMIN_EMAIL=admin | Variable | Default | Description | | --- | --- | --- | | `DOMAIN` | *(empty — IP mode)* | Domain for automatic HTTPS | -| `HOST_IP` | *(auto-detected)* | Public IP of the machine | +| `HOST_IP` | *(auto-detected)* | Public IPv4 address of the machine | +| `HOST_IP6` | *(auto-detected in dual mode)* | Public IPv6 address of the machine. Only populated when `IP_FAMILY` is `dual`. | +| `IP_FAMILY` | `ipv4` | IP family: `ipv4`, `ipv6`, or `dual`. Controls which address(es) the installer detects and which DNS record types are shown. | | `CADDY_HTTP_PORT` | `80` | HTTP port | | `CADDY_HTTPS_PORT` | `443` | HTTPS port | | `ADMIN_EMAIL` | *(empty)* | Admin account email. When set, the installer pre-creates the admin via the auth API after services start. | @@ -175,12 +177,32 @@ nixopus restart When you provide a `DOMAIN`, Caddy automatically obtains and renews TLS certificates from Let's Encrypt. For this to work: -1. **DNS A record** must point to your machine's public IP *before* installing. +1. **DNS record** must point to your machine's public IP *before* installing — an A record for IPv4, AAAA for IPv6, or both for dual-stack. 2. **Port 80 must be open** — Let's Encrypt uses HTTP-01 challenges on port 80, even if you only serve on 443. 3. **Not behind a proxy** — If using Cloudflare, set to "DNS only" (grey cloud) during initial setup so the challenge can reach your machine directly. You can re-enable proxying after the first certificate is issued. Without a `DOMAIN`, Nixopus runs in IP mode over plain HTTP. +### IPv6 and dual-stack + +Set `IP_FAMILY` to control which IP address(es) the installer detects and which DNS records are required: + +| `IP_FAMILY` | Detected addresses | Required DNS | +| --- | --- | --- | +| `ipv4` (default) | IPv4 only | A record | +| `ipv6` | IPv6 only | AAAA record | +| `dual` | Both IPv4 and IPv6 | A + AAAA records | + +```bash +# IPv6-only install +curl -fsSL install.nixopus.com | sudo IP_FAMILY=ipv6 DOMAIN=panel.example.com bash + +# Dual-stack install +curl -fsSL install.nixopus.com | sudo IP_FAMILY=dual DOMAIN=panel.example.com bash +``` + +In `dual` mode, the installer stores both `HOST_IP` (IPv4) and `HOST_IP6` (IPv6) in the `.env` file. The completion banner shows both A and AAAA record instructions. + ## Viewing secrets ```bash diff --git a/self-hosting/installation.mdx b/self-hosting/installation.mdx index 06dbd15..268146b 100644 --- a/self-hosting/installation.mdx +++ b/self-hosting/installation.mdx @@ -61,9 +61,13 @@ Other Linux distributions may work if Docker and Compose V2 are already installe - If you want automatic HTTPS, create a DNS A record pointing your domain to the machine's public IP **before** running the installer. + If you want automatic HTTPS, create a DNS record pointing your domain to the machine's public IP **before** running the installer: - Skip this step to run in IP mode over plain HTTP. + - **IPv4** (default): create an **A** record + - **IPv6**: create an **AAAA** record + - **Dual-stack**: create both **A** and **AAAA** records + + Skip this step to run in IP mode over plain HTTP. See [IPv6 and dual-stack](/self-hosting/configuration#ipv6-and-dual-stack) for details. Configure your installation using the builder below. Select your options and the command updates in real time — then copy and run it on your server. diff --git a/self-hosting/management-cli.mdx b/self-hosting/management-cli.mdx index 1b868ee..3e761b5 100644 --- a/self-hosting/management-cli.mdx +++ b/self-hosting/management-cli.mdx @@ -20,9 +20,9 @@ sudo nixopus status | `nixopus stop` | Stop all services | | `nixopus config` | Show current configuration | | `nixopus config set KEY=VALUE` | Update a config value (restart required) | -| `nixopus domain add ` | Switch to domain-based HTTPS | +| `nixopus domain add [flags]` | Switch to domain-based HTTPS | | `nixopus domain remove` | Switch back to IP-based HTTP | -| `nixopus ip set ` | Change host IP | +| `nixopus ip set [flags] ` | Change host IP | | `nixopus port set ` | Change a port | | `nixopus backup` | Backup database and config | | `nixopus admin-bootstrap [email] [password]` | Create the initial admin via the auth API | @@ -61,16 +61,50 @@ Ensure DNS is configured before running this. ```bash nixopus domain add panel.example.com -nixopus restart +``` + +#### Domain flags + +| Flag | Description | +| --- | --- | +| `--ipv4` | Use IPv4 (A record). This is the default. | +| `--ipv6` | Use IPv6 (AAAA record). | +| `--verify=auto\|strict\|off` | DNS verification mode (default `auto`). `auto` warns on mismatch but proceeds. `strict` aborts on mismatch. `off` skips verification entirely (use when behind Cloudflare or a proxy). | + +The `--ipv4`/`--ipv6` flag overrides the instance-level `IP_FAMILY` for this command only. When omitted, the configured `IP_FAMILY` is used. + +```bash +# Add domain with IPv6 +nixopus domain add panel.example.com --ipv6 + +# Add domain behind Cloudflare proxy (skip DNS check) +nixopus domain add panel.example.com --verify=off + +# Strict verification — abort if DNS doesn't match +nixopus domain add panel.example.com --verify=strict ``` ### Switch back to IP mode ```bash nixopus domain remove -nixopus restart ``` +### Change host IP + +```bash +# Set IPv4 (default) +nixopus ip set 93.184.216.34 + +# Set IPv6 explicitly +nixopus ip set --ipv6 2001:db8::1 + +# Auto-detected: addresses containing ":" are treated as IPv6 +nixopus ip set 2001:db8::1 +``` + +When setting an IPv6 address while `IP_FAMILY` is still `ipv4`, the CLI prints a hint to enable dual-stack with `nixopus config set IP_FAMILY=dual`. + ### Update a config value ```bash