From e1f3ad61fb29205a8f3c8c8ab42f0a291fea03fe Mon Sep 17 00:00:00 2001
From: Johan Siebens <johan.siebens@gmail.com>
Date: Sat, 26 Apr 2025 21:54:11 +0200
Subject: [PATCH] chore: updates docs

---
 mkdocs/docs/configuration/auth-oidc.md     | 191 +++++++++++++++++++++
 mkdocs/docs/configuration/dns-providers.md | 176 +++++++++++++++++++
 mkdocs/docs/getting-started/docker.md      |  72 --------
 mkdocs/docs/getting-started/index.md       |  84 +++++++++
 mkdocs/docs/getting-started/manual.md      | 115 -------------
 mkdocs/docs/getting-started/tailnet.md     | 191 +++++++++++++++++++++
 mkdocs/docs/index.md                       |  47 +++--
 mkdocs/docs/installation/docker.md         | 101 +++++++++++
 mkdocs/docs/installation/index.md          |  38 ++++
 mkdocs/docs/installation/linux.md          | 155 +++++++++++++++++
 mkdocs/docs/overview/features.md           |  59 +++++++
 mkdocs/docs/stylesheets/extra.css          | 126 ++++++++++++++
 mkdocs/mkdocs.yml                          | 113 ++++++++++--
 13 files changed, 1245 insertions(+), 223 deletions(-)
 create mode 100644 mkdocs/docs/configuration/auth-oidc.md
 create mode 100644 mkdocs/docs/configuration/dns-providers.md
 delete mode 100644 mkdocs/docs/getting-started/docker.md
 create mode 100644 mkdocs/docs/getting-started/index.md
 delete mode 100644 mkdocs/docs/getting-started/manual.md
 create mode 100644 mkdocs/docs/getting-started/tailnet.md
 create mode 100644 mkdocs/docs/installation/docker.md
 create mode 100644 mkdocs/docs/installation/index.md
 create mode 100644 mkdocs/docs/installation/linux.md
 create mode 100644 mkdocs/docs/overview/features.md
 create mode 100644 mkdocs/docs/stylesheets/extra.css

diff --git a/mkdocs/docs/configuration/auth-oidc.md b/mkdocs/docs/configuration/auth-oidc.md
new file mode 100644
index 0000000..0b79207
--- /dev/null
+++ b/mkdocs/docs/configuration/auth-oidc.md
@@ -0,0 +1,191 @@
+# Configuring authentication with OIDC
+
+While ionscale can operate without an OIDC (OpenID Connect) provider using only static keys, configuring an OIDC provider is highly recommended for enhanced security, user management, and a smoother administrative experience.
+
+## Why configure an OIDC provider?
+
+Without an OIDC provider, ionscale operates in a key-only mode:
+
+- System administrators can only use the system admin key for administrative tasks
+- Tailscale devices can only connect using [tags](https://tailscale.com/kb/1068/tags) and [pre-authentication keys](https://tailscale.com/kb/1085/auth-keys)
+- No user accounts or user-specific permissions are available
+
+With an OIDC provider configured:
+
+- Users can authenticate using their existing identity provider credentials
+- Administrators can assign specific permissions to users
+- System administration can be delegated to specific users
+- Fine-grained access control based on user identity becomes possible
+- More seamless user experience with browser-based authentication
+
+## Supported OIDC providers
+
+ionscale supports any standard OIDC provider, including:
+
+- Google Workspace
+- Auth0
+- Okta
+- Azure AD / Microsoft Entra ID
+- Keycloak
+- GitLab
+- GitHub (OAuth 2.0 with OIDC extensions)
+- And many others
+
+## Basic OIDC configuration
+
+To configure an OIDC provider, update your ionscale configuration file (`config.yaml`) with the following settings:
+
+```yaml
+auth:
+  provider:
+    # OIDC issuer URL where ionscale can find the OpenID Provider Configuration Document
+    issuer: "https://your-oidc-provider.com"
+    # OIDC client ID and secret
+    client_id: "your-client-id"
+    client_secret: "your-client-secret"
+    # Optional: additional OIDC scopes used in the OIDC flow
+    additional_scopes: "groups"
+```
+
+### Required configuration fields
+
+- `issuer`: The URL to your OIDC provider's issuer. This URL is used to discover your provider's endpoints.
+- `client_id`: The client ID from your OIDC provider application registration.
+- `client_secret`: The client secret from your OIDC provider application registration.
+
+### Optional configuration
+
+- `additional_scopes`: A space-separated list of additional OAuth scopes to request during authentication.
+  By default, ionscale requests the `openid`, `email`, and `profile` scopes.
+
+## Configuring your OIDC provider
+
+When registering ionscale with your OIDC provider, you'll need to configure the following:
+
+**Redirect URI**: Set to `https://your-ionscale-domain.com/auth/callback`
+
+## System administrator access
+
+With OIDC configured, you'll want to specify which users have system administrator privileges.
+This is done in the `auth.system_admins` section of your configuration:
+
+```yaml
+auth:
+  # Configuration from previous section...
+
+  system_admins:
+    # By email address
+    emails:
+      - "admin@example.com"
+      - "secadmin@example.com"
+    
+    # By subject identifier (sub claim from OIDC)
+    subs:
+      - "user|123456"
+    
+    # By attribute expression (using BEXPR syntax)
+    filters:
+      - "token.groups contains \"admin\""
+      - "domain == \"admin.example.com\""
+```
+
+You can use one or more of these methods to designate system administrators:
+
+1. **By Email**: List specific email addresses that should have admin privileges.
+2. **By Subject ID**: List specific user IDs (the `sub` claim from your OIDC provider).
+3. **By Expression**: Use BEXPR filters to determine admin status based on token claims.
+
+## OIDC authentication flow
+
+When a user attempts to authenticate with ionscale:
+
+1. The user is redirected to the OIDC provider's login page.
+2. After successful authentication, the user is redirected back to ionscale.
+3. ionscale verifies the authentication and checks if:
+   - The user is a system administrator (based on the `system_admins` configuration).
+   - The user has access to any tailnets (based on IAM policies configured for individual tailnets).
+
+## Provider-specific setup instructions
+
+### Google
+
+1. Go to the [Google Cloud Console](https://console.cloud.google.com/).
+2. Create a new project or select an existing one.
+3. Navigate to "APIs & Services" > "Credentials".
+4. Click "Create Credentials" > "OAuth client ID".
+5. Select "Web application" as the application type.
+6. Add `https://your-ionscale-domain.com/auth/callback` as an authorized redirect URI.
+7. Copy the client ID and client secret.
+
+Configure ionscale:
+```yaml
+auth:
+  provider:
+    issuer: "https://accounts.google.com"
+    client_id: "your-client-id.apps.googleusercontent.com"
+    client_secret: "your-client-secret"
+```
+
+### Auth0
+
+1. Go to the [Auth0 Dashboard](https://manage.auth0.com/).
+2. Create a new application or select an existing one of type "Regular Web Application".
+3. Under "Settings", configure:
+   - Allowed Callback URLs: `https://your-ionscale-domain.com/auth/callback`
+4. Copy the Domain, Client ID, and Client Secret.
+
+Configure ionscale:
+```yaml
+auth:
+  provider:
+    issuer: "https://your-tenant.auth0.com/"
+    client_id: "your-client-id"
+    client_secret: "your-client-secret"
+```
+
+### Microsoft Azure AD / Entra ID
+
+1. Go to the [Azure Portal](https://portal.azure.com/).
+2. Navigate to "Azure Active Directory" > "App registrations".
+3. Create a new registration.
+4. Add `https://your-ionscale-domain.com/auth/callback` as a redirect URI of type "Web".
+5. Under "Certificates & secrets", create a new client secret.
+6. Copy the Application (client) ID and the new secret.
+
+Configure ionscale:
+```yaml
+auth:
+  provider:
+    issuer: "https://login.microsoftonline.com/your-tenant-id/v2.0"
+    client_id: "your-client-id"
+    client_secret: "your-client-secret"
+    additional_scopes: "offline_access"
+```
+
+## Complete configuration example
+
+```yaml
+auth:
+  provider:
+    issuer: "https://accounts.google.com"
+    client_id: "your-client-id.apps.googleusercontent.com"
+    client_secret: "your-client-secret"
+    additional_scopes: "groups"
+  
+  system_admins:
+    emails:
+      - "admin@example.com"
+    filters:
+      - "domain == \"example.com\" && token.groups contains \"admin\""
+```
+
+## OIDC without system admin
+
+If you've configured OIDC but no system administrators, you can still use the system admin key from your initial setup for administrative tasks:
+
+```bash
+export IONSCALE_URL="https://your-ionscale-domain.com"
+export IONSCALE_KEY="your-system-admin-key"
+ionscale tailnet list
+```
+
diff --git a/mkdocs/docs/configuration/dns-providers.md b/mkdocs/docs/configuration/dns-providers.md
new file mode 100644
index 0000000..3da960e
--- /dev/null
+++ b/mkdocs/docs/configuration/dns-providers.md
@@ -0,0 +1,176 @@
+# Configuring DNS providers
+
+ionscale supports integration with various DNS providers to enable Tailscale's HTTPS certificate functionality. When a DNS provider is properly configured, ionscale can automatically manage TXT records required for the DNS-01 challenge when requesting certificates.
+
+## Why configure a DNS provider
+
+While not strictly required for basic ionscale operation, configuring a DNS provider enables important Tailscale features:
+
+1. **Tailscale HTTPS Certificates**: Allows nodes to receive valid HTTPS certificates for their Tailscale hostnames, enabling secure web services within your tailnet.
+2. **Tailscale Serve**: Supports the `tailscale serve` feature, which allows users to easily share web services with proper HTTPS.
+
+Without a configured DNS provider, these features will not be available to your users.
+
+## Supported DNS providers
+
+ionscale uses the [libdns](https://github.com/libdns) libraries to support the following DNS providers:
+
+- [Azure DNS](https://github.com/libdns/azure)
+- [Cloudflare](https://github.com/libdns/cloudflare)
+- [DigitalOcean](https://github.com/libdns/digitalocean)
+- [Google Cloud DNS](https://github.com/libdns/googleclouddns)
+- [Amazon Route 53](https://github.com/libdns/route53)
+
+!!! info "Provider availability"
+    These are the DNS providers supported at the time of this writing. Since ionscale uses the libdns ecosystem, additional providers may be added in future releases as the ecosystem expands.
+    
+    If you need support for a different DNS provider, check the [libdns GitHub organization](https://github.com/libdns) for newly available providers or consider contributing an implementation for your provider.
+
+!!! note "Future plugin system"
+    A plugin system for DNS providers is currently in the ideation phase. This would make it significantly easier to add and configure additional DNS providers without modifying the core ionscale code. Stay tuned for updates on this feature in future releases.
+
+## DNS provider configuration
+
+To configure a DNS provider, add the appropriate settings to your ionscale configuration file (`config.yaml`):
+
+```yaml
+dns:
+  # The base domain for MagicDNS FQDN hostnames
+  magic_dns_suffix: "ionscale.net"
+  
+  # DNS provider configuration for HTTPS certificates
+  provider:
+    # Name of your DNS provider
+    name: "cloudflare"
+    # The DNS zone to use (typically your domain name)
+    zone: "example.com"
+    # Provider-specific configuration (varies by provider)
+    config:
+      # Provider-specific credentials and settings go here
+      # See provider-specific examples below
+```
+
+### Important requirements
+
+1. The `magic_dns_suffix` must be a subdomain of the provider's zone (or the zone itself).
+2. MagicDNS must be enabled for the tailnet to use HTTPS certificates.
+3. You must have administrative access to the DNS zone to configure the provider.
+
+## Provider-specific examples
+
+### Cloudflare
+
+```yaml
+dns:
+  magic_dns_suffix: "ts.example.com"
+  provider:
+    name: "cloudflare"
+    zone: "example.com"
+    config:
+      auth_token: "your-cloudflare-api-token"
+      # OR use email/api_key authentication 
+      # email: "your-email@example.com"
+      # api_key: "your-global-api-key"
+```
+
+For Cloudflare, create an API token with the "Edit" permission for "Zone:DNS".
+
+### Azure DNS
+
+```yaml
+dns:
+  magic_dns_suffix: "ts.example.com"
+  provider:
+    name: "azure"
+    zone: "example.com"
+    config:
+      tenant_id: "your-tenant-id"
+      client_id: "your-client-id"
+      client_secret: "your-client-secret"
+      subscription_id: "your-subscription-id"
+      resource_group_name: "your-resource-group"
+```
+
+For Azure, create a service principal with "DNS Zone Contributor" role for your DNS zone's resource group.
+
+### Amazon Route 53
+
+```yaml
+dns:
+  magic_dns_suffix: "ts.example.com"
+  provider:
+    name: "route53"
+    zone: "example.com"
+    config:
+      access_key_id: "your-access-key-id"
+      secret_access_key: "your-secret-access-key"
+      # Optional region, defaults to us-east-1
+      region: "us-east-1"
+```
+
+For AWS Route 53, create an IAM user with permissions to modify records in your hosted zone.
+
+### Google Cloud DNS
+
+```yaml
+dns:
+  magic_dns_suffix: "ts.example.com"
+  provider:
+    name: "googleclouddns"
+    zone: "example-com" # Note: GCP uses zone names without dots
+    config:
+      project: "your-project-id"
+      # Either provide service account JSON directly
+      service_account_json: '{"type":"service_account","project_id":"your-project",...}'
+      # OR specify a path to a service account key file
+      # service_account_key_file: "/path/to/service-account-key.json"
+```
+
+For Google Cloud DNS, create a service account with the "DNS Administrator" role.
+
+### DigitalOcean
+
+```yaml
+dns:
+  magic_dns_suffix: "ts.example.com"
+  provider:
+    name: "digitalocean"
+    zone: "example.com"
+    config:
+      token: "your-digitalocean-api-token"
+```
+
+For DigitalOcean, create an API token with read and write access.
+
+## Enabling HTTPS certificates for a tailnet
+
+After configuring a DNS provider in your ionscale server, you can enable HTTPS certificates for a tailnet:
+
+```bash
+# Enable MagicDNS and HTTPS certificates for a tailnet
+ionscale dns update --tailnet "my-tailnet" --magic-dns --https-certs
+```
+
+## Verifying DNS provider configuration
+
+To verify that your DNS provider is correctly configured:
+
+1. Configure a tailnet with MagicDNS and HTTPS certificates enabled.
+2. Connect a device to the tailnet.
+3. On the device, run:
+   ```bash
+   tailscale cert <hostname>
+   ```
+4. If successful, the command will obtain a certificate for the hostname.
+5. You should see TXT records created in your DNS zone for the ACME challenge.
+
+## Troubleshooting
+
+If you encounter issues with DNS provider integration:
+
+1. **Check DNS Provider Credentials**: Ensure the credentials in your configuration have sufficient permissions.
+2. **Verify Zone Configuration**: Make sure the zone in your configuration matches your actual DNS zone.
+3. **Check MagicDNS Settings**: Confirm that `magic_dns_suffix` is properly configured as a subdomain of your zone.
+4. **Review Server Logs**: The ionscale server logs may contain error messages related to DNS provider integration.
+5. **Test DNS Record Creation**: Some providers offer tools to test API access for creating and updating DNS records.
+
diff --git a/mkdocs/docs/getting-started/docker.md b/mkdocs/docs/getting-started/docker.md
deleted file mode 100644
index d6113f4..0000000
--- a/mkdocs/docs/getting-started/docker.md
+++ /dev/null
@@ -1,72 +0,0 @@
-# Getting started with Docker
-
-You can install and run __ionscale__ using the Docker images published on [GitHub Container Registry](https://github.com/jsiebens/ionscale/pkgs/container/ionscale).
-
-## Requirements 
-
-- A Linux machine with port 443 and 3478 open to ingress traffic.
-- Docker installed. See the [official installation documentation](https://docs.docker.com/install/)
-- A registered domain name.
-
-## Step 1. Configure DNS
-
-Set up a `A` DNS records: `ionscale.example.com` (We are assuming that your domain name is example.com.)
-
-!!! tip
-
-    You can use `dig` to make sure that DNS records are propagated:
-
-    ``` bash
-    $ dig ionscale.example.com
-    ```
-
-## Step 2. Run ionscale with Docker
-
-### Configure ionscale
-
-``` bash
-mkdir -p ionscale/data
-cd ./ionscale
-```
-
-Generate a configuration file for __ionscale__ with the following commands:
-
-``` bash
-export IONSCALE_ACME_EMAIL=<your email>
-export IONSCALE_DOMAIN=ionscale.example.com
-export IONSCALE_SYSTEM_ADMIN_KEY=$(docker run ghcr.io/jsiebens/ionscale:0.15.0 genkey -n)
-```
-
-``` bash
-tee ./config.yaml >/dev/null <<EOF
-listen_addr: ":443"
-public_addr: "${IONSCALE_DOMAIN}:443"
-stun_public_addr: "${IONSCALE_DOMAIN}:3478"
-
-tls:
-  acme: true
-  acme_email: "${IONSCALE_ACME_EMAIL}"
-
-keys:
-  system_admin_key: "${IONSCALE_SYSTEM_ADMIN_KEY}"
-  
-database:
-  url: "/data/ionscale.db?_pragma=busy_timeout(5000)&_pragma=journal_mode(WAL)"
-
-logging:
-  level: info
-EOF
-```
-
-### Start ionscale
-
-Run an __ionscale__ instance with the following command:
-
-``` bash
-docker run \
-  -v $(pwd)/config.yaml:/etc/ionscale/config.yaml \
-  -v $(pwd)/data:/data \
-  -p 443:443 \
-  -p 3478:3478/udp \
-  ghcr.io/jsiebens/ionscale:0.15.0 server --config /etc/ionscale/config.yaml
-```
\ No newline at end of file
diff --git a/mkdocs/docs/getting-started/index.md b/mkdocs/docs/getting-started/index.md
new file mode 100644
index 0000000..c505394
--- /dev/null
+++ b/mkdocs/docs/getting-started/index.md
@@ -0,0 +1,84 @@
+# Getting started with ionscale
+
+After installing ionscale, you'll need to configure the CLI to interact with your server. This guide will walk you through the initial setup and explain the authentication options available.
+
+## Installing the ionscale CLI
+
+The ionscale CLI is the primary tool for managing your ionscale instance. It allows you to create and manage tailnets, users, and access controls.
+
+```bash
+# Download the CLI (adjust the URL for your system architecture)
+curl -L -o ionscale https://github.com/jsiebens/ionscale/releases/download/v0.16.0/ionscale_linux_amd64
+
+# Make it executable
+chmod +x ionscale
+
+# Move to system path
+sudo mv ionscale /usr/local/bin/
+```
+
+## Authentication requirements
+
+To use the ionscale CLI, you must authenticate with the server using one of two methods:
+
+!!! important "Administrator access required"
+    All management operations require either:
+    
+    1. **System admin key** authentication, or
+    2. **OIDC user** authentication with system administrator privileges
+
+### Option 1: Using the system admin key
+
+If you configured ionscale with a system admin key during installation, you can authenticate using that key:
+
+```bash
+# Configure environment variables
+export IONSCALE_URL="https://ionscale.example.com"
+export IONSCALE_KEY="your-system-admin-key"
+
+# Verify connection
+ionscale version
+```
+
+The system admin key provides full administrative access to your ionscale instance. This is the default authentication method when OIDC is not configured.
+
+### Option 2: Using OIDC authentication
+
+If you configured ionscale with an OIDC provider, users designated as system administrators in the OIDC configuration can authenticate:
+
+```bash
+# Configure URL only
+export IONSCALE_URL="https://ionscale.example.com"
+
+# Authenticate through OIDC
+ionscale auth login
+```
+
+This will open a browser window where you can authenticate with your OIDC provider. After successful authentication, if your account has system administrator privileges, you'll be able to use the CLI.
+
+!!! tip "OIDC system administrators"
+    System administrators are defined in the ionscale configuration under the `auth.system_admins` section. See the [Authentication with OIDC](../configuration/auth-oidc.md) documentation for details.
+
+## Basic CLI commands
+
+Once authenticated, you can use the ionscale CLI to manage your instance:
+
+```bash
+# View general information
+ionscale version                # Show version information
+ionscale help                   # Display help information
+
+# Tailnet management
+ionscale tailnet list           # List all tailnets
+ionscale tailnet create -n NAME # Create a new tailnet
+
+# Auth key management
+ionscale auth-key list --tailnet NAME    # List auth keys for a tailnet
+ionscale auth-key create --tailnet NAME  # Create a new auth key
+```
+
+## Next steps
+
+After setting up the CLI, you can:
+
+1. [Create your first tailnet](tailnet.md)
\ No newline at end of file
diff --git a/mkdocs/docs/getting-started/manual.md b/mkdocs/docs/getting-started/manual.md
deleted file mode 100644
index 09cbcd9..0000000
--- a/mkdocs/docs/getting-started/manual.md
+++ /dev/null
@@ -1,115 +0,0 @@
-# Getting started on a Linux Server
-
-This tutorial will guide you through the steps needed to install and run __ionscale__ on a Linux machine.
-
-## Prerequisites 
-
-- A Linux machine with port 443 and 3478 open to ingress traffic.
-- A registered domain name.
-
-## Step 1. Configure DNS
-
-Set up a `A` DNS records: `ionscale.example.com` (We are assuming that your domain name is example.com.)
-
-!!! tip
-
-    You can use `dig` to make sure that DNS records are propagated:
-
-    ``` bash
-    $ dig ionscale.example.com
-    ```
-
-## Step 2. Set up ionscale on your Linux host
-
-### Prepare installation
-
-Run the following commands to prepare the installation:
-
-``` bash
-sudo mkdir -p /etc/ionscale
-sudo mkdir -p /var/lib/ionscale
-
-sudo useradd --system --no-create-home --shell /bin/false ionscale
-sudo chown ionscale:ionscale /etc/ionscale
-sudo chown ionscale:ionscale /var/lib/ionscale
-```
-
-### Install ionscale
-
-Run the following commands to install the __ionscale__ binary on your Linux host:
-
-``` bash
-sudo curl \
-    -o "/usr/local/bin/ionscale" \
-    -sfL "https://github.com/jsiebens/ionscale/releases/download/v0.15.0/ionscale_linux_amd64"
-
-sudo chmod +x "/usr/local/bin/ionscale"
-```
-
-### Configure ionscale
-
-Generate a system admin key for __ionscale__ using the `ionscale genkey` command and write it the an environment file:
-
-``` bash
-sudo tee /etc/default/ionscale >/dev/null <<EOF
-IONSCALE_KEYS_SYSTEM_ADMIN_KEY=$(ionscale genkey -n)
-EOF
-```
-
-Generate a configuration file for __ionscale__ with the following commands:
-
-``` bash
-export IONSCALE_ACME_EMAIL=<your email>
-export IONSCALE_DOMAIN=ionscale.example.com
-```
-
-``` bash
-sudo tee /etc/ionscale/config.yaml >/dev/null <<EOF
-listen_addr: ":443"
-public_addr: "${IONSCALE_DOMAIN}:443"
-stun_public_addr: "${IONSCALE_DOMAIN}:3478"
-
-tls:
-  acme: true
-  acme_email: "${IONSCALE_ACME_EMAIL}"
-
-database:
-  url: "/var/lib/ionscale/ionscale.db?_pragma=busy_timeout(5000)&_pragma=journal_mode(WAL)"
-
-logging:
-  level: info
-EOF
-```
-
-Create a systemd service file for __ionscale__ with the following commands:
-
-``` bash
-sudo tee /etc/systemd/system/ionscale.service >/dev/null <<EOF
-[Unit]
-Description=ionscale - a Tailscale Controller server
-Requires=network-online.target
-After=network.target
-
-[Service]
-EnvironmentFile=/etc/default/ionscale
-User=ionscale
-Group=ionscale
-ExecStart=/usr/local/bin/ionscale server --config /etc/ionscale/config.yaml
-Restart=on-failure
-RestartSec=10s
-AmbientCapabilities=CAP_NET_BIND_SERVICE
-
-[Install]
-WantedBy=multi-user.target
-EOF
-```
-
-### Start ionscale
-
-On your Linux machine, run the following commands to enable and start the __ionscale__ daemon:
-
-``` bash
-sudo systemctl daemon-reload
-sudo systemctl enable ionscale
-sudo systemctl start ionscale
-```
diff --git a/mkdocs/docs/getting-started/tailnet.md b/mkdocs/docs/getting-started/tailnet.md
new file mode 100644
index 0000000..2379cd9
--- /dev/null
+++ b/mkdocs/docs/getting-started/tailnet.md
@@ -0,0 +1,191 @@
+# Creating your first tailnet
+
+A tailnet is a private network that connects your devices securely using Tailscale. This guide will walk you through creating your first tailnet with ionscale.
+
+## Prerequisites
+
+Before creating a tailnet, make sure you have:
+
+- ionscale server installed and running
+- The ionscale CLI installed and configured
+- Authentication with system administrator privileges
+
+## Creating a tailnet
+
+The simplest way to create a tailnet is with the `tailnet create` command:
+
+```bash
+ionscale tailnet create --name "my-first-tailnet"
+```
+
+This creates a basic tailnet named "my-first-tailnet" with:
+
+- A default ACL policy that allows all connections 
+```
+{"acls": [{"action": "accept", "src": ["*"], "dst": ["*:*"]}]}
+```
+- A default IAM policy that determines who can access the tailnet
+
+!!! note
+    The tailnet name must be unique within your ionscale instance and should only contain alphanumeric characters, hyphens, and underscores.
+
+## Setting IAM policies for access control
+
+!!! important "OIDC required"
+    IAM policies are only relevant when an OIDC provider is configured. If your ionscale instance isn't using OIDC, access to tailnets is managed solely through auth keys, and the configuration in this section won't apply.
+
+When using OIDC authentication, you'll need to configure who can access your tailnet through IAM policies.
+
+### Configuring IAM during tailnet creation
+
+You can set a basic IAM policy when creating a tailnet using flags:
+
+```bash
+# Allow all users with an @example.com email address
+ionscale tailnet create --name "company-tailnet" --domain "example.com"
+
+# Allow only a specific user
+ionscale tailnet create --name "personal-tailnet" --email "user@example.com"
+```
+
+These flags provide quick ways to set up common IAM policies:
+
+- `--domain example.com`: Creates a **shared tailnet** that allows all users with an email address from the specified domain. This is ideal for company or team networks where multiple users need access. The IAM policy will contain a filter rule like `domain == "example.com"`.
+
+- `--email user@example.com`: Creates a **personal tailnet** that grants access only to the specific email address. This is suitable for individual use or when you want to tightly control access to a specific user. The IAM policy will contain an entry for the specified email.
+
+!!! note
+    You can't use both flags together. Choose either domain-based access for a shared network or email-based access for a personal network.
+
+### Configuring IAM after tailnet creation
+
+You can view and update the IAM policy for an existing tailnet:
+
+```bash
+# View current IAM policy
+ionscale iam get-policy --tailnet "my-first-tailnet"
+
+# Update IAM policy using a JSON file
+ionscale iam update-policy --tailnet "my-first-tailnet" --file policy.json
+```
+
+Example policy.json file:
+```json
+{
+  "filters": ["domain == example.com"],
+  "emails": ["specific-user@otherdomain.com"],
+  "roles": {
+    "admin@example.com": "admin"
+  }
+}
+```
+
+## Connecting devices to your tailnet
+
+How devices connect to your tailnet depends on your authentication configuration:
+
+### Using OIDC authentication
+
+If OIDC is configured, users with access (based on the IAM policy) connect via web authentication:
+
+```bash
+tailscale up --login-server=https://ionscale.example.com
+```
+
+This opens a browser window where users authenticate with the OIDC provider. After successful authentication, if the user has access based on the tailnet's IAM policy, the device will be connected.
+
+### Using auth keys
+
+Auth keys allow devices to join a tailnet without interactive authentication. This is useful for automated deployments, servers, or environments where browser-based authentication isn't practical.
+
+There are two main scenarios for creating auth keys:
+
+#### Without OIDC configured
+
+When OIDC is not configured, a system administrator must create auth keys with appropriate tags:
+
+```bash
+# Create an auth key with a tag
+ionscale auth-key create --tailnet "my-first-tailnet" --tags "tag:server"
+```
+
+The tags assigned to the key will determine what network access the device has once connected, based on your ACL rules.
+
+#### With OIDC configured
+
+When OIDC is configured, any user with access to a tailnet can create auth keys for that tailnet:
+
+```bash
+# As an authenticated user, create an auth key
+ionscale auth-key create --tailnet "my-first-tailnet"
+```
+
+Additionally, system administrators can create auth keys with specific tags:
+
+```bash
+# As a system administrator, create a key with tags
+ionscale auth-key create --tailnet "my-first-tailnet" --tags "tag:database"
+```
+
+#### Connecting with auth keys
+
+To connect a device using an auth key:
+
+```bash
+# Connect using the auth key
+tailscale up --login-server=https://ionscale.example.com --auth-key=...
+```
+
+!!! note
+    Auth keys in ionscale are single-use by default. Once a key has been used to authenticate a device, it cannot be used again.
+
+## Configuring ACL policies
+
+Access Control Lists (ACLs) define what network access is allowed within a tailnet. By default, tailnets are created with an open policy that allows all connections.
+
+To update the ACL policy:
+
+```bash
+# View current ACL policy
+ionscale acl get --tailnet "my-first-tailnet"
+
+# Update ACL policy
+ionscale acl update --tailnet "my-first-tailnet" --file acl.json
+```
+
+Example acl.json with more restrictive rules:
+```json
+{
+  "acls": [
+    {"action": "accept", "src": ["tag:web"], "dst": ["tag:db:5432"]},
+    {"action": "accept", "src": ["group:admins"], "dst": ["*:*"]}
+  ],
+  "groups": {
+    "admins": ["admin@example.com"]
+  },
+  "tagOwners": {
+    "tag:web": ["admin@example.com"],
+    "tag:db": ["admin@example.com"]
+  }
+}
+```
+
+!!! tip
+    ACLs give you fine-grained control over which devices can communicate within your tailnet. For more information, see the [Tailscale ACL documentation](https://tailscale.com/kb/1018/acls/).
+
+## Managing multiple tailnets
+
+You can create multiple tailnets to separate different network environments:
+
+```bash
+# List all tailnets
+ionscale tailnet list
+
+# Create tailnets for different teams or businesses
+ionscale tailnet create --name "tailnet-a"
+ionscale tailnet create --name "tailnet-b"
+ionscale tailnet create --name "tailnet-c"
+```
+
+!!! note
+    Each tailnet is a separate network with its own devices, ACLs, and IAM policies. Devices in different tailnets cannot communicate with each other by default.
\ No newline at end of file
diff --git a/mkdocs/docs/index.md b/mkdocs/docs/index.md
index 397b3f7..52b7b0e 100644
--- a/mkdocs/docs/index.md
+++ b/mkdocs/docs/index.md
@@ -1,35 +1,30 @@
-# ionscale
+# Welcome to ionscale
 
-> **Note**:
-> ionscale is currently beta quality, actively being developed and so subject to changes
+ionscale is an open-source alternative to Tailscale's control server, designed to provide a self-hosted coordination service for your Tailscale networks.
 
-**What is Tailscale?**
+!!! info "Beta status"
+    ionscale is currently in beta. While it's stable for production use for small tailnets, we're actively developing new features and improvements.
 
-[Tailscale](https://tailscale.com) is a VPN service that makes the devices and applications you own accessible anywhere in the world, securely and effortlessly.
-It enables encrypted point-to-point connections using the open source [WireGuard](https://www.wireguard.com/) protocol, which means only devices on your private network can communicate with each other.
+## What is ionscale?
 
-**What is ionscale?**
+Tailscale allows your devices to communicate securely across networks using WireGuard®. While Tailscale's client software is open source, their centralized coordination server (which manages public keys and network configurations) is proprietary.
 
-While the Tailscale software running on each node is open source, their centralized "coordination server" which act as a shared drop box for public keys is not.
+**ionscale aims to implement a lightweight, open-source control server that:**
 
-_ionscale_ aims to implement such lightweight, open source alternative Tailscale control server.
+- Acts as a drop-in replacement for Tailscale's coordination server
+- Can be self-hosted on your infrastructure
+- Gives you full control over your network configuration
+- Works with the standard Tailscale clients
+- Supports a [wide range of Tailscale features](./overview/features.md)
 
-## Features
+## Getting started
 
-- multi [tailnet](https://tailscale.com/kb/1136/tailnet/) support
-- multi user support
-- OIDC integration (not required, although recommended)
-- [Auth keys](https://tailscale.com/kb/1085/auth-keys/)
-- [Access control list](https://tailscale.com/kb/1018/acls/)
-- [DNS](https://tailscale.com/kb/1054/dns/)
-    - nameservers
-    - Split DNS
-    - MagicDNS
-- [HTTPS Certs](https://tailscale.com/kb/1153/enabling-https/)
-- [Tailscale SSH](https://tailscale.com/kb/1193/tailscale-ssh/)
-- [Service collection](https://tailscale.com/kb/1100/services/)
-- [Taildrop](https://tailscale.com/kb/1106/taildrop/)
+- [**Installation guide**](./installation/index.md) - Install ionscale using Docker or directly on Linux
+- [**CLI configuration**](./getting-started/index.md) - Set up the ionscale CLI and authenticate
+- [**Creating a tailnet**](./getting-started/tailnet.md) - Create and manage your first tailnet
+- [**OIDC authentication**](./configuration/auth-oidc.md) - Configure user authentication via OIDC
+- [**DNS providers**](./configuration/dns-providers.md) - Set up DNS integration for HTTPS certificates
 
-## Disclaimer
-
-This is not an official Tailscale or Tailscale Inc. project.
\ No newline at end of file
+<small>
+Disclaimer: This is not an official Tailscale or Tailscale Inc. project. Tailscale and WireGuard are trademarks of their respective owners.
+</small>
\ No newline at end of file
diff --git a/mkdocs/docs/installation/docker.md b/mkdocs/docs/installation/docker.md
new file mode 100644
index 0000000..af1cea2
--- /dev/null
+++ b/mkdocs/docs/installation/docker.md
@@ -0,0 +1,101 @@
+# Installing ionscale with Docker
+
+This guide will walk you through installing and configuring ionscale using Docker containers. Docker provides a simple and consistent way to deploy ionscale across different environments.
+
+## Prerequisites
+
+Before you begin, make sure you have:
+
+- A Linux server (virtual or physical)
+- Docker installed ([official Docker installation guide](https://docs.docker.com/engine/install/))
+- Root or sudo access
+- A registered domain name pointing to your server
+- Ports 443 (HTTPS) and 3478/UDP (STUN) open in your firewall
+- Basic familiarity with the Linux command line
+
+## Domain and DNS configuration
+
+ionscale requires a domain name to function properly. This enables secure HTTPS connections and proper Tailscale device discovery.
+
+1. Configure an A record in your domain's DNS settings:
+   ```
+   ionscale.example.com  →  YOUR_SERVER_IP
+   ```
+   (Replace "example.com" with your actual domain and "YOUR_SERVER_IP" with your server's public IP address)
+
+2. Verify the DNS record has propagated:
+   ```bash
+   dig ionscale.example.com
+   ```
+   The command should return your server's public IP address.
+
+## Container setup
+
+### Creating a directory structure
+
+Create a dedicated directory for ionscale files:
+
+```bash
+mkdir -p ionscale/data
+cd ./ionscale
+```
+
+### Generating a configuration file
+
+First, set up environment variables for the configuration:
+
+```bash
+export IONSCALE_ACME_EMAIL="your-email@example.com"  # Used for Let's Encrypt notifications
+export IONSCALE_DOMAIN="ionscale.example.com"        # Your ionscale domain
+export IONSCALE_SYSTEM_ADMIN_KEY=$(docker run --rm ghcr.io/jsiebens/ionscale:0.16.0 genkey -n)
+```
+
+!!! important "System admin key"
+    The system admin key is a critical security component that provides full administrative access to your ionscale instance. Make sure to save this key securely.
+    
+    Alternatively, you can configure ionscale without a system admin key by using an OIDC provider and setting up system admin accounts through the OIDC configuration. See the [Authentication with OIDC](../configuration/auth-oidc.md) documentation for details.
+
+Now create the configuration file:
+
+```bash
+cat > ./config.yaml <<EOF
+listen_addr: ":443"
+public_addr: "${IONSCALE_DOMAIN}:443"
+stun_public_addr: "${IONSCALE_DOMAIN}:3478"
+
+tls:
+  acme: true
+  acme_email: "${IONSCALE_ACME_EMAIL}"
+
+keys:
+  system_admin_key: "${IONSCALE_SYSTEM_ADMIN_KEY}"
+  
+database:
+  url: "/data/ionscale.db?_pragma=busy_timeout(5000)&_pragma=journal_mode(WAL)"
+
+logging:
+  level: info
+EOF
+```
+
+### Running the container
+
+Start the ionscale container with the following command:
+
+```bash
+docker run -d \
+  --name ionscale \
+  --restart unless-stopped \
+  -v $(pwd)/config.yaml:/etc/ionscale/config.yaml \
+  -v $(pwd)/data:/data \
+  -p 443:443 \
+  -p 3478:3478/udp \
+  ghcr.io/jsiebens/ionscale:0.16.0 server --config /etc/ionscale/config.yaml
+```
+
+This command:
+
+- Creates a persistent container named "ionscale"
+- Mounts your configuration file and data directory
+- Maps the required ports to the host
+- Automatically restarts the container if it stops unexpectedly
diff --git a/mkdocs/docs/installation/index.md b/mkdocs/docs/installation/index.md
new file mode 100644
index 0000000..c251e11
--- /dev/null
+++ b/mkdocs/docs/installation/index.md
@@ -0,0 +1,38 @@
+# Installation guide
+
+ionscale can be installed in several ways, depending on your preferences and requirements. This section covers the different installation methods available.
+
+## Choose your installation method
+
+ionscale offers two primary installation methods:
+
+### Docker installation
+
+The [Docker installation](docker.md) method is recommended for:
+
+- Quick deployments
+- Testing and evaluation
+- Users familiar with container environments
+- Simplified upgrades and maintenance
+
+Docker provides an isolated environment with all dependencies included, making it the easiest way to get started with ionscale.
+
+### Linux installation
+
+The [Linux installation](linux.md) method is suitable for:
+
+- Production environments
+- Integration with existing infrastructure
+- More control over the installation
+- Systems without Docker
+
+This approach installs ionscale directly on your Linux server and configures it as a system service.
+
+## Post-installation steps
+
+After completing the installation, consider these next steps:
+
+1. Configure an [OIDC provider](../configuration/auth-oidc.md) for user authentication
+2. Set up a [DNS provider](../configuration/dns-providers.md) to enable HTTPS certificates for Tailscale nodes
+3. Create and configure tailnets
+4. Set up access controls and permissions
\ No newline at end of file
diff --git a/mkdocs/docs/installation/linux.md b/mkdocs/docs/installation/linux.md
new file mode 100644
index 0000000..aa258c4
--- /dev/null
+++ b/mkdocs/docs/installation/linux.md
@@ -0,0 +1,155 @@
+# Linux installation
+
+This guide walks you through installing ionscale directly on a Linux server. This approach gives you more control over the installation and is suitable for production environments.
+
+## Prerequisites
+
+Before you begin, make sure you have:
+
+- A Linux server (virtual or physical)
+- Root or sudo access
+- A registered domain name pointing to your server
+- Ports 443 (HTTPS) and 3478/UDP (STUN) open in your firewall
+- Basic familiarity with the Linux command line
+
+## Domain and DNS configuration
+
+ionscale requires a domain name to function properly. This enables secure HTTPS connections and proper Tailscale device discovery.
+
+1. Configure an A record in your domain's DNS settings:
+   ```
+   ionscale.example.com  →  YOUR_SERVER_IP
+   ```
+   (Replace "example.com" with your actual domain and "YOUR_SERVER_IP" with your server's public IP address)
+
+2. Verify the DNS record has propagated:
+   ```bash
+   dig ionscale.example.com
+   ```
+   The command should return your server's public IP address.
+
+## System preparation
+
+### Create a dedicated service user
+
+For security reasons, ionscale should run under a dedicated, unprivileged system user:
+
+```bash
+# Create directories
+sudo mkdir -p /etc/ionscale
+sudo mkdir -p /var/lib/ionscale
+
+# Create service user
+sudo useradd --system --no-create-home --shell /bin/false ionscale
+
+# Set appropriate permissions
+sudo chown ionscale:ionscale /etc/ionscale
+sudo chown ionscale:ionscale /var/lib/ionscale
+```
+
+## Installation
+
+### Download and install the binary
+
+Install the ionscale binary on your system:
+
+```bash
+# Download the latest version (adjust for your CPU architecture)
+sudo curl -o "/usr/local/bin/ionscale" \
+  -sfL "https://github.com/jsiebens/ionscale/releases/download/v0.16.0/ionscale_linux_amd64"
+
+# Make it executable
+sudo chmod +x "/usr/local/bin/ionscale"
+
+# Verify installation
+ionscale version
+```
+
+### Configuration
+
+1. Generate a system admin key and store it in an environment file:
+
+```bash
+sudo tee /etc/default/ionscale >/dev/null <<EOF
+IONSCALE_KEYS_SYSTEM_ADMIN_KEY=$(ionscale genkey -n)
+EOF
+```
+
+!!! important "System admin key"
+    The system admin key is a critical security component that provides full administrative access to your ionscale instance. Make sure to save this key securely.
+    
+    Alternatively, you can configure ionscale without a system admin key by using an OIDC provider and setting up system admin accounts through the OIDC configuration. See the [Authentication with OIDC](../configuration/auth-oidc.md) documentation for details.
+
+2. Set up environment variables for the configuration:
+
+```bash
+export IONSCALE_ACME_EMAIL="your-email@example.com"  # For Let's Encrypt notifications
+export IONSCALE_DOMAIN="ionscale.example.com"        # Your ionscale domain
+```
+
+3. Create the configuration file:
+
+```bash
+sudo tee /etc/ionscale/config.yaml >/dev/null <<EOF
+listen_addr: ":443"
+public_addr: "${IONSCALE_DOMAIN}:443"
+stun_public_addr: "${IONSCALE_DOMAIN}:3478"
+
+tls:
+  acme: true
+  acme_email: "${IONSCALE_ACME_EMAIL}"
+
+database:
+  url: "/var/lib/ionscale/ionscale.db?_pragma=busy_timeout(5000)&_pragma=journal_mode(WAL)"
+
+logging:
+  level: info
+EOF
+```
+
+## Setting up systemd service
+
+Create a systemd service file to manage the ionscale process:
+
+```bash
+sudo tee /etc/systemd/system/ionscale.service >/dev/null <<EOF
+[Unit]
+Description=ionscale - a Tailscale control server
+Requires=network-online.target
+After=network.target
+
+[Service]
+EnvironmentFile=/etc/default/ionscale
+User=ionscale
+Group=ionscale
+ExecStart=/usr/local/bin/ionscale server --config /etc/ionscale/config.yaml
+Restart=on-failure
+RestartSec=10s
+AmbientCapabilities=CAP_NET_BIND_SERVICE
+
+[Install]
+WantedBy=multi-user.target
+EOF
+```
+
+The `AmbientCapabilities=CAP_NET_BIND_SERVICE` line allows ionscale to bind to privileged ports (443) without running as root.
+
+## Starting ionscale
+
+Enable and start the ionscale service:
+
+```bash
+# Reload systemd to recognize the new service
+sudo systemctl daemon-reload
+
+# Enable service to start on boot
+sudo systemctl enable ionscale
+
+# Start the service
+sudo systemctl start ionscale
+
+# Check status
+sudo systemctl status ionscale
+```
+
+If everything started successfully, you should see an "active (running)" status.
diff --git a/mkdocs/docs/overview/features.md b/mkdocs/docs/overview/features.md
new file mode 100644
index 0000000..0c69a6a
--- /dev/null
+++ b/mkdocs/docs/overview/features.md
@@ -0,0 +1,59 @@
+# Supported features
+
+ionscale implements key Tailscale features to provide a complete control server experience. This page outlines the major features that ionscale supports.
+
+## Multi-tailnet support
+
+ionscale allows you to create and manage multiple tailnets (Tailscale private networks) from a single server:
+
+- Create isolated networks for different teams or environments
+- Manage separate tailnets for personal and organizational use
+- Configure each tailnet with its own ACLs and settings
+
+## User management
+
+- **Multi-user support**: Multiple users can access and use the same tailnet based on permissions
+- **OIDC integration**: Optional but recommended for user authentication and management
+
+## Authentication
+
+- **[Auth keys](https://tailscale.com/kb/1085/auth-keys/)**: Generate and manage pre-authentication keys for devices
+- **[Device tagging](https://tailscale.com/kb/1068/tags/)**: Apply tags to devices for better management and ACL control
+
+## Network control
+
+- **[Access control lists (ACLs)](https://tailscale.com/kb/1018/acls/)**: Define fine-grained rules for who can access what
+- **[Subnet routers](https://tailscale.com/kb/1019/subnets/)**: Connect existing networks to your tailnet
+- **[Exit nodes](https://tailscale.com/kb/1103/exit-nodes/)**: Configure nodes to act as VPN exit points
+
+## DNS management
+
+- **[MagicDNS](https://tailscale.com/kb/1081/magicdns/)**: Automatic DNS for tailnet devices
+- **[Split DNS](https://tailscale.com/kb/1054/dns/)**: Route specific DNS queries to specific resolvers
+- **Custom nameservers**: Configure any DNS servers for your tailnet
+
+## HTTPS and certificates
+
+- **[HTTPS certificates](https://tailscale.com/kb/1153/enabling-https/)**: Automatic SSL/TLS certificates for devices
+- **DNS provider integration**: Support for various DNS providers to facilitate ACME challenges
+- **[Tailscale Serve](https://tailscale.com/kb/1242/tailscale-serve/)**: Share web services easily with HTTPS
+
+## SSH
+
+- **[Tailscale SSH](https://tailscale.com/kb/1193/tailscale-ssh/)**: Built-in SSH server support
+- **SSH policy management**: Control who can SSH into which devices
+
+## DERP
+
+- **Embedded DERP server**
+- **Custom DERP maps**: Configure your own DERP servers
+
+## File sharing
+
+- **[Taildrop](https://tailscale.com/kb/1106/taildrop/)**: Send files directly between tailnet devices
+
+## Feature status
+
+Most features are fully implemented and compatible with the official Tailscale clients. As ionscale is continuously developed, new features from Tailscale are regularly added.
+
+If you find any issues with specific features or have requests for additional functionality, please check the [project repository](https://github.com/jsiebens/ionscale) for the latest updates or to submit feedback.
\ No newline at end of file
diff --git a/mkdocs/docs/stylesheets/extra.css b/mkdocs/docs/stylesheets/extra.css
new file mode 100644
index 0000000..13123f5
--- /dev/null
+++ b/mkdocs/docs/stylesheets/extra.css
@@ -0,0 +1,126 @@
+/* Custom CSS for ionscale documentation */
+
+/* Enhance code blocks */
+.md-typeset pre {
+  border-radius: 6px;
+  box-shadow: 0 2px 6px rgba(0, 0, 0, 0.12);
+}
+
+/* Enhance code block headers */
+.md-typeset code {
+  border-radius: 3px;
+  font-size: 0.9em;
+  padding: 0.2em 0.4em;
+}
+
+/* Make admonitions stand out more */
+.md-typeset .admonition {
+  border-radius: 4px;
+  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.05);
+  margin: 1.5em 0;
+}
+
+.md-typeset .admonition-title {
+  padding-left: 2.5rem;
+}
+
+/* Make tables more professional */
+.md-typeset table:not([class]) {
+  border-radius: 6px;
+  box-shadow: 0 1px 4px rgba(0, 0, 0, 0.08);
+  overflow: hidden;
+}
+
+.md-typeset table:not([class]) th {
+  background-color: rgba(63, 81, 181, 0.08);
+  font-weight: 600;
+}
+
+/* Enhance UI element spacing */
+.md-typeset ul li,
+.md-typeset ol li {
+  margin-bottom: 0.35em;
+}
+
+.md-typeset h1,
+.md-typeset h2,
+.md-typeset h3,
+.md-typeset h4 {
+  font-weight: 500;
+  margin-top: 1.5em;
+}
+
+.md-typeset h2 {
+  border-bottom: 1px solid rgba(63, 81, 181, 0.1);
+  padding-bottom: 0.3em;
+}
+
+/* Subtle border on the right for table of contents */
+.md-sidebar--secondary {
+  border-left: 1px solid rgba(0, 0, 0, 0.07);
+  background-color: rgba(0, 0, 0, 0.01);
+}
+
+/* Navigation improvements */
+.md-nav__item .md-nav__link--active {
+  font-weight: 600;
+}
+
+/* Responsive improvements */
+@media screen and (min-width: 76.25em) {
+  .md-sidebar--primary {
+    border-right: 1px solid rgba(0, 0, 0, 0.07);
+    background-color: rgba(0, 0, 0, 0.01);
+  }
+}
+
+/* Better footer */
+.md-footer-meta {
+  background-color: rgba(0, 0, 0, 0.87);
+}
+
+/* Remove the logo and style site name */
+.md-header__button.md-logo {
+  display: none;
+}
+
+/* Move the site name to the left */
+.md-header__title {
+  margin-left: 0;
+  font-weight: 500;
+  letter-spacing: 0.02em;
+  font-family: Lato, sans-serif;
+}
+
+.md-header__topic {
+  color: white;
+  font-size: 1.2rem;
+  line-height: 2.4rem;
+  margin-left: 0.6rem;
+}
+
+/* Badge styles for version/status indicators */
+.md-typeset .md-badge {
+  border-radius: 4px;
+  display: inline-block;
+  font-size: 0.75em;
+  font-weight: 700;
+  padding: 4px 6px;
+  margin: 0 0.5em;
+  vertical-align: middle;
+}
+
+.md-typeset .md-badge--new {
+  background-color: #28a745;
+  color: white;
+}
+
+.md-typeset .md-badge--beta {
+  background-color: #f0ad4e;
+  color: white;
+}
+
+.md-typeset .md-badge--deprecated {
+  background-color: #dc3545;
+  color: white;
+}
\ No newline at end of file
diff --git a/mkdocs/mkdocs.yml b/mkdocs/mkdocs.yml
index 9d2de5e..a4b39c9 100644
--- a/mkdocs/mkdocs.yml
+++ b/mkdocs/mkdocs.yml
@@ -1,28 +1,51 @@
 site_name: ionscale
 
-repo_name: jsiebens/ionscale
-repo_url: https://github.com/jsiebens/ionscale
-edit_uri: ""
+# Remove the GitHub repository link from the top-right corner
+# repo_name: jsiebens/ionscale
+# repo_url: https://github.com/jsiebens/ionscale
+# edit_uri: ""
 
 nav:
   - Overview:
       - Introduction: index.md
+      - Supported Features: overview/features.md
   - Installation:
-      - Manual: ./getting-started/manual.md
-      - Docker: ./getting-started/docker.md
+      - Installation: ./installation/index.md
+      - Linux installation: ./installation/linux.md
+      - Docker installation: ./installation/docker.md
+  - Getting started:
+      - Getting started: ./getting-started/index.md
+      - Creating a tailnet: ./getting-started/tailnet.md
   - Configuration:
+      - OIDC: ./configuration/auth-oidc.md
+      - DNS providers: ./configuration/dns-providers.md
       - Reference: ./configuration/reference.md
 
 theme:
   name: material
   custom_dir: overrides
+  
+  # Custom stylesheets
+  extra_css:
+    - stylesheets/extra.css
+  
+  # Explicitly disable the logo to show only the site name
+  #logo: ""
+  favicon: assets/favicon.png
 
+  # Enhanced color scheme
   palette:
-    - scheme: default
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: indigo
+      accent: indigo
       toggle:
         icon: material/toggle-switch-off-outline
         name: Switch to dark mode
-    - scheme: slate
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: indigo
+      accent: indigo
       toggle:
         icon: material/toggle-switch
         name: Switch to light mode
@@ -32,9 +55,28 @@ theme:
     code: Roboto Mono
 
   features:
+    # Navigation
     - navigation.tracking
     - navigation.sections
-    - toc.integrate
+    - navigation.indexes
+    - navigation.top         # Back-to-top button
+    - navigation.footer      # Footer with previous/next links
+    
+    # Content
+    - content.code.copy      # Add copy button to code blocks
+    - content.code.annotate  # Allow code annotations
+    - content.tabs.link      # Sync all tabs with the same label
+    
+    # Search
+    - search.highlight
+    - search.share
+    - search.suggest
+    
+    # Table of contents
+    - toc.follow
+  
+  # Hide the table of contents on the navigation
+  toc_depth: 0
 
   include_search_page: false
   search_index_only: true
@@ -42,15 +84,66 @@ theme:
   language: en
 
 markdown_extensions:
+  # Admonitions and callouts
   - admonition
   - pymdownx.details
-  - pymdownx.superfences
+  
+  # Code blocks with syntax highlighting
   - pymdownx.highlight:
       anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
   - pymdownx.inlinehilite
+  
+  # Code annotations
   - pymdownx.snippets
-  - pymdownx.superfences
+  
+  # Tabbed content
+  - pymdownx.tabbed:
+      alternate_style: true
+  
+  # Content tabs
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  
+  # Better formatting options
+  - attr_list             # Add HTML attributes and CSS classes
+  - def_list              # Definition lists
+  - md_in_html            # Markdown within HTML
+  - tables                # Tables
+  - footnotes             # Footnotes
+  
+  # Typography improvements
+  - pymdownx.critic       # Track changes
+  - pymdownx.caret        # Superscript/subscript
+  - pymdownx.mark         # Highlighting
+  - pymdownx.tilde        # Strikethrough
+  - pymdownx.smartsymbols # Smart symbols (arrows, fractions)
 
 extra:
+  # Page status annotations
+  status:
+    new: Recently added
+    deprecated: No longer supported
+    beta: Currently in beta
+  
+  # Enhanced social cards
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/jsiebens/ionscale
+    - icon: fontawesome/brands/docker
+      link: https://github.com/jsiebens/ionscale/pkgs/container/ionscale
+  
+  # Page customization
+  version:
+    provider: mike
+  
+  # Footer customization
+  generator: false  # Hide "Made with Material for MkDocs"
+  
+  # Analytics (existing)
   analytics:
     provider: custom
\ No newline at end of file