Skip to content

docs: add IPv6/IP family and dual-stack documentation #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
raghavyuva wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: add IPv6/IP family and dual-stack documentation #3

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 12 additions & 2 deletions concepts/domains.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
```

<Note>
Expand Down
26 changes: 24 additions & 2 deletions self-hosting/configuration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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. |
Expand Down Expand Up @@ -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
Expand Down
8 changes: 6 additions & 2 deletions self-hosting/installation.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,9 +61,13 @@ Other Linux distributions may work if Docker and Compose V2 are already installe

<Steps>
<Step title="Point DNS (optional)">
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.
</Step>
<Step title="Build your install command">
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.
Expand Down
42 changes: 38 additions & 4 deletions self-hosting/management-cli.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <domain>` | Switch to domain-based HTTPS |
| `nixopus domain add <domain> [flags]` | Switch to domain-based HTTPS |
| `nixopus domain remove` | Switch back to IP-based HTTP |
| `nixopus ip set <ip>` | Change host IP |
| `nixopus ip set [flags] <ip>` | Change host IP |
| `nixopus port set <http\|https\|ssh> <port>` | Change a port |
| `nixopus backup` | Backup database and config |
| `nixopus admin-bootstrap [email] [password]` | Create the initial admin via the auth API |
Expand Down Expand Up @@ -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
Expand Down