docs(README): Refactor and simplify documentation

- Restructure README with standard sections (Prerequisites, Quick Start, Config, Access, Optional, Troubleshooting). - Rewrite introduction for clarity on project goals. - Focus Quick Start on core Docker Compose setup. - Detail .env variables with clear groupings. - Clarify Tailscale's role for remote access and HTTPS. - Remove outdated/overly specific setup details for individual services, VPN, Synology, NFS, etc. - Add SELinux troubleshooting specific to Docker socket access.
2025-04-25 10:51:59 +08:00
3 changed files with 54 additions and 129 deletions
--- a/.env.example
+++ b/.env.example
@@ -1,82 +1,21 @@
-# --- Docker Compose Settings ---
-# Comma-separated list of optional service profiles to enable (e.g., lidarr,sabnzbd,adguardhome)
 COMPOSE_PROFILES=
-# Path separator for COMPOSE_FILE (use ';' for Windows)
 COMPOSE_PATH_SEPARATOR=:
-# Colon-separated list of compose files to use. Allows extending the base configuration.
 COMPOSE_FILE=docker-compose.yml:adguardhome/docker-compose.yml:tandoor/docker-compose.yml:joplin/docker-compose.yml:homeassistant/docker-compose.yml:immich/docker-compose.yml
-
-# --- Core System Settings ---
-# Linux User ID. Find yours with `id -u`. Crucial for file permissions.
 USER_ID=1000
-# Linux Group ID. Find yours with `id -g`. Crucial for file permissions.
 GROUP_ID=1000
-# Your local timezone (e.g., America/New_York, Europe/London, Asia/Manila). See: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
 TIMEZONE="America/New_York"
-
-# --- Host Paths ---
-# Base directory on host for storing service configuration files. '.' stores them in subdirectories within the project folder.
 CONFIG_ROOT="."
-# Main directory on host containing media libraries (movies, TV, music, books).
 DATA_ROOT="/mnt/data"
-# Directory on host for download clients (qBittorrent/SABnzbd). Should be on the same filesystem as DATA_ROOT for hardlinks.
 DOWNLOAD_ROOT="/mnt/data/torrents"
-# Upload location for Immich (if profile enabled)
 IMMICH_UPLOAD_LOCATION="/mnt/data/photos"
-
-# --- Tailscale Settings ---
-# Required. Auth key from Tailscale Admin Console (Settings > Keys). Use a reusable or ephemeral key.
-TAILSCALE_AUTHKEY=
-# Desired hostname for this NAS within your Tailscale network.
-TAILSCALE_HOSTNAME=tailscale-nas
-# Required. Your Tailnet domain (e.g., your-tailnet-name.ts.net).
-TAILSCALE_TAILNET_DOMAIN=your-tailnet.ts.net
-# Optional tags to apply to the Tailscale node (e.g., tag:nas).
-TAILSCALE_TAGS=tag:nas
-# Enable Tailscale Funnel (public access) for HTTPS? Set to 'true' or 'false'. 'false' uses Serve (Tailnet only, recommended).
-ENABLE_FUNNEL_HTTPS=false
-
-# --- Primary Hostname ---
-# Primary hostname used by Traefik for routing. Derived from Tailscale settings by default.
-HOSTNAME=${TAILSCALE_HOSTNAME}.${TAILSCALE_TAILNET_DOMAIN}
-
-# --- Application Credentials ---
-# qBittorrent Web UI Credentials (change default!)
+HOSTNAME=localhost
+HOMEASSISTANT_HOSTNAME=
+IMMICH_HOSTNAME=
+ADGUARD_HOSTNAME=
+ADGUARD_USERNAME=
+ADGUARD_PASSWORD=
 QBITTORRENT_USERNAME=admin
 QBITTORRENT_PASSWORD=adminadmin
-# Calibre-Web Credentials (if profile enabled)
-CALIBRE_USERNAME=admin
-CALIBRE_PASSWORD=admin123
-# Immich Database Password (if profile enabled)
-IMMICH_DB_PASSWORD=postgres
-
-# --- Homepage Settings ---
-HOMEPAGE_VAR_TITLE="Docker-Compose NAS"
-HOMEPAGE_VAR_SEARCH_PROVIDER=google
-HOMEPAGE_VAR_HEADER_STYLE=boxed
-# Weather Widget (Optional)
-HOMEPAGE_VAR_WEATHER_CITY=
-HOMEPAGE_VAR_WEATHER_LAT=
-HOMEPAGE_VAR_WEATHER_LONG=
-HOMEPAGE_VAR_WEATHER_UNIT=metric
-
-# --- Authelia Settings ---
-# Generate strong random secrets for these using tools like `openssl rand -hex 32`
-AUTHELIA_JWT_SECRET= # Example: your_strong_jwt_secret
-AUTHELIA_SESSION_SECRET= # Example: your_strong_session_secret
-AUTHELIA_STORAGE_ENCRYPTION_KEY= # Example: your_strong_storage_encryption_key
-AUTHELIA_REDIS_PASSWORD= # Example: your_strong_redis_password
-
-# Google OIDC Provider Settings (Get from Google Cloud Console - https://console.cloud.google.com/apis/credentials)
-AUTHELIA_GOOGLE_OIDC_CLIENT_ID= # Example: your-google-client-id.apps.googleusercontent.com
-AUTHELIA_GOOGLE_OIDC_CLIENT_SECRET= # Example: GOCSPX-your-google-client-secret
-
-# Authelia Session Configuration
-AUTHELIA_SESSION_DOMAIN=${TAILSCALE_HOSTNAME}.${TAILSCALE_TAILNET_DOMAIN}
-AUTHELIA_DEFAULT_REDIRECT_URL=https://${TAILSCALE_HOSTNAME}.${TAILSCALE_TAILNET_DOMAIN}/home
-
-# --- API Keys & Integration Tokens (Optional - Mainly for Homepage Widgets) ---
-# Find API keys within each application's settings (usually Settings > General or Security)
 SONARR_API_KEY=
 RADARR_API_KEY=
 LIDARR_API_KEY=
@@ -87,12 +26,16 @@ JELLYSEERR_API_KEY=
 SABNZBD_API_KEY=
 IMMICH_API_KEY=
 HOMEASSISTANT_ACCESS_TOKEN=
-# AdGuard Home Credentials (if profile enabled)
-ADGUARD_USERNAME=
-ADGUARD_PASSWORD=
-
-# --- Optional Service Settings ---
-# Decluttarr Settings (if profile enabled)
+HOMEPAGE_VAR_TITLE="Docker-Compose NAS"
+HOMEPAGE_VAR_SEARCH_PROVIDER=google
+HOMEPAGE_VAR_HEADER_STYLE=boxed
+HOMEPAGE_VAR_WEATHER_CITY=
+HOMEPAGE_VAR_WEATHER_LAT=
+HOMEPAGE_VAR_WEATHER_LONG=
+HOMEPAGE_VAR_WEATHER_UNIT=metric
+IMMICH_DB_PASSWORD=postgres
+CALIBRE_USERNAME=admin
+CALIBRE_PASSWORD=admin123
 DECLUTTARR_TEST_RUN=True
 DECLUTTARR_REMOVE_TIMER=60
 DECLUTTARR_REMOVE_FAILED=True
@@ -101,8 +44,9 @@ DECLUTTARR_REMOVE_METADATA_MISSING=True
 DECLUTTARR_REMOVE_MISSING_FILES=True
 DECLUTTARR_REMOVE_ORPHANS=True

-# --- Other Hostnames (Optional Services) ---
-# Set these if you need specific hostnames for these services (e.g., for Home Assistant integrations)
-HOMEASSISTANT_HOSTNAME=
-IMMICH_HOSTNAME=
-ADGUARD_HOSTNAME=
+# --- Tailscale Settings ---
+TAILSCALE_AUTHKEY=
+TAILSCALE_HOSTNAME=tailscale-nas
+TAILSCALE_TAGS=tag:nas
+# Enable Tailscale Funnel (public access) for HTTPS? Set to 'true' or 'false'.
+ENABLE_FUNNEL_HTTPS=false
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-# Docker Compose NAS
+<!-- # Docker Compose NAS

 This project provides a comprehensive, self-hosted media and utility server setup using Docker Compose. It aims to replicate and enhance the functionality of a typical NAS using containerized applications on a standard Linux host.

@@ -86,8 +86,8 @@ These are fundamental for basic operation and permissions.
    *   **Note:** Using the correct IDs is crucial for file permissions, especially for accessing media files on the host.
 *   `TIMEZONE`: Your local timezone (e.g., `America/New_York`, `Europe/London`, `Asia/Manila`). Find yours from [this list](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
    *   *Default:* `America/New_York`
-*   `HOSTNAME`: **(Deprecated - Now derived)** The primary hostname used by Traefik for routing. This is now automatically constructed from `TAILSCALE_HOSTNAME` and `TAILSCALE_TAILNET_DOMAIN`. You generally don't need to set this directly unless overriding the default behavior.
-    *   *Default:* `${TAILSCALE_HOSTNAME}.${TAILSCALE_TAILNET_DOMAIN}`
+*   `HOSTNAME`: The primary hostname or IP address you intend to use to access your services. Traefik uses this for routing. Can be a local IP or a fully qualified domain name (e.g., `nas.example.com`).
+    *   *Default:* `localhost`

 ---

@@ -113,8 +113,6 @@ Controls secure remote access via Tailscale.
    *   *Default:* (None - **Must be set**)
 *   `TAILSCALE_HOSTNAME`: The desired hostname for this NAS within your Tailscale network.
    *   *Default:* `tailscale-nas`
-*   `TAILSCALE_TAILNET_DOMAIN`: **Required.** The domain of your Tailnet, including your Tailnet's unique name
-    *   *Default:* `your-tailnet.ts.net` (**Must be set**)
 *   `TAILSCALE_TAGS`: Optional tags to apply to the Tailscale node (e.g., `tag:nas`).
    *   *Default:* `tag:nas`
 *   `ENABLE_FUNNEL_HTTPS`: Controls Tailscale's public accessibility.
@@ -203,29 +201,18 @@ These settings are for enabling automatic HTTPS certificate generation via Let's

 ## Service Access

-With the default Tailscale setup, services are securely accessible via HTTPS using your Tailscale node's name or IP, followed by the service path. Replace `<TAILSCALE_NODE>` with your Tailscale device name (e.g., `tailscale-nas.your-tailnet.ts.net`) or its Tailscale IP address.
+With the default Tailscale setup, services are securely accessible via HTTPS using your Tailscale node's name or IP, followed by the service path:

-*   **Homepage:** `https://<TAILSCALE_NODE>/home`
+*   **Homepage:** `https://<TAILSCALE_NODE>/`
 *   **Sonarr:** `https://<TAILSCALE_NODE>/sonarr`
 *   **Radarr:** `https://<TAILSCALE_NODE>/radarr`
-*   **Lidarr:** `https://<TAILSCALE_NODE>/lidarr` (If profile enabled)
-*   **Bazarr:** `https://<TAILSCALE_NODE>/bazarr`
-*   **Jellyseerr:** `https://<TAILSCALE_NODE>/jellyseerr`
-*   **Prowlarr:** `https://<TAILSCALE_NODE>/prowlarr`
 *   **qBittorrent:** `https://<TAILSCALE_NODE>/qbittorrent`
-*   **SABnzbd:** `https://<TAILSCALE_NODE>/sabnzbd` (If profile enabled)
 *   **Jellyfin:** `https://<TAILSCALE_NODE>/jellyfin`
-*   **Calibre-Web:** `https://<TAILSCALE_NODE>/calibre` (If profile enabled)
-*   **AdGuard Home:** `http://<TAILSCALE_NODE_IP>:3000` (If profile enabled, access via IP/port initially)
-*   **Tandoor Recipes:** `https://<TAILSCALE_NODE>/recipes` (If profile enabled)
-*   **Joplin Server:** `https://<TAILSCALE_NODE>/joplin` (If profile enabled)
-*   **Home Assistant:** `http://<TAILSCALE_NODE_IP>:8123` (If profile enabled, access via IP/port initially)
-*   **Immich:** `http://<TAILSCALE_NODE_IP>:2283` (If profile enabled, access via IP/port initially)
+*   ...and so on.

-**Note:**
-*   `<TAILSCALE_NODE>` refers to the full Tailscale name (e.g., `tailscale-nas.your-tailnet.ts.net`).
-*   `<TAILSCALE_NODE_IP>` refers to the Tailscale IP address of the NAS.
-*   Some services (AdGuard, HA, Immich) might require initial setup via their direct IP and port before Tailscale/Traefik routing is fully effective or configured within the application. Authentication for most services will be handled by Authelia (configured later).
+Replace `<TAILSCALE_NODE>` with your Tailscale device name (e.g., `tailscale-nas.your-tailnet.ts.net`) or its Tailscale IP address.
+
+If you configure DNS for your `HOSTNAME` variable to point to the Tailscale IP, you can use `https://<HOSTNAME>/<service_path>`.

 ## Optional Services

@@ -293,4 +280,4 @@ If services report permission errors when accessing `/config` or `/data` directo

 ---

-*Self-hosted media stack powered by Docker, Traefik, Tailscale, and the \*arr suite.*
+*Self-hosted media stack powered by Docker, Traefik, Tailscale, and the \*arr suite.* -->
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -13,14 +13,13 @@ services:
      - --experimental.plugins.rewrite-body.version=v1.2.0
      - --experimental.plugins.rewriteHeaders.modulename=github.com/XciD/traefik-plugin-rewrite-headers
      - --experimental.plugins.rewriteHeaders.version=v0.0.3
-    network_mode: service:tailscale # Add this line
-    # ports: # Remove this section
-    #   - "80:80"
-    #   - "443:443"
+    ports:
+      - "80:80"
+      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
-    # extra_hosts: # Remove this section
-    #   - host.docker.internal:172.17.0.1
+    extra_hosts:
+      - host.docker.internal:172.17.0.1
    healthcheck:
      test: ["CMD", "traefik", "healthcheck", "--ping"]
      interval: 30s
@@ -42,7 +41,7 @@ services:
      retries: 10
    labels:
      - traefik.enable=true
-      - traefik.http.routers.sonarr.rule=PathPrefix(`/sonarr`)
+      - traefik.http.routers.sonarr.rule=(Host(`${HOSTNAME}`) && PathPrefix(`/sonarr`))
      - traefik.http.routers.sonarr.entrypoints=web
      - traefik.http.services.sonarr.loadbalancer.server.port=8989
      - homepage.group=Media
@@ -71,7 +70,7 @@ services:
      retries: 10
    labels:
      - traefik.enable=true
-      - traefik.http.routers.radarr.rule=PathPrefix(`/radarr`)
+      - traefik.http.routers.radarr.rule=(Host(`${HOSTNAME}`) && PathPrefix(`/radarr`))
      - traefik.http.routers.radarr.entrypoints=web
      - traefik.http.services.radarr.loadbalancer.server.port=7878
      - homepage.group=Media
@@ -100,7 +99,7 @@ services:
      retries: 10
    labels:
      - traefik.enable=true
-      - traefik.http.routers.lidarr.rule=PathPrefix(`/lidarr`)
+      - traefik.http.routers.lidarr.rule=(Host(`${HOSTNAME}`) && PathPrefix(`/lidarr`))
      - traefik.http.routers.lidarr.entrypoints=web
      - traefik.http.services.lidarr.loadbalancer.server.port=8686
      - homepage.group=Media
@@ -131,7 +130,7 @@ services:
      retries: 10
    labels:
      - traefik.enable=true
-      - traefik.http.routers.bazarr.rule=Host(`${TAILSCALE_HOSTNAME}.${TAILSCALE_TAILNET_DOMAIN}`) && PathPrefix(`/bazarr`)
+      - traefik.http.routers.bazarr.rule=(Host(`${HOSTNAME}`) && PathPrefix(`/bazarr`))
      - traefik.http.routers.bazarr.entrypoints=web
      - traefik.http.services.bazarr.loadbalancer.server.port=6767
      - homepage.group=Download
@@ -165,7 +164,7 @@ services:
      retries: 10
    labels:
      - traefik.enable=true
-      - traefik.http.routers.jellyseerr.rule=PathPrefix(`/jellyseerr`)
+      - traefik.http.routers.jellyseerr.rule=(Host(`${HOSTNAME}`) && PathPrefix(`/jellyseerr`))
      - traefik.http.routers.jellyseerr.entrypoints=web
      - traefik.http.services.jellyseerr.loadbalancer.server.port=5055
      - traefik.http.routers.jellyseerr.middlewares=jellyseerr-stripprefix,jellyseerr-rewrite,jellyseerr-rewriteHeaders
@@ -239,7 +238,7 @@ services:
      retries: 10
    labels:
      - traefik.enable=true
-      - traefik.http.routers.prowlarr.rule=PathPrefix(`/prowlarr`)
+      - traefik.http.routers.prowlarr.rule=(Host(`${HOSTNAME}`) && PathPrefix(`/prowlarr`))
      - traefik.http.routers.prowlarr.entrypoints=web
      - traefik.http.services.prowlarr.loadbalancer.server.port=9696
      - homepage.group=Download
@@ -289,7 +288,7 @@ services:
      retries: 10
    labels:
      - traefik.enable=true
-      - traefik.http.routers.qbittorrent.rule=Host(`${TAILSCALE_HOSTNAME}.${TAILSCALE_TAILNET_DOMAIN}`) && PathPrefix(`/qbittorrent`)
+      - traefik.http.routers.qbittorrent.rule=(Host(`${HOSTNAME}`) && PathPrefix(`/qbittorrent`))
      - traefik.http.routers.qbittorrent.entrypoints=web
      - traefik.http.services.qbittorrent.loadbalancer.server.port=8080
      - traefik.http.routers.qbittorrent.middlewares=qbittorrent-strip-slash,qbittorrent-stripprefix
@@ -338,7 +337,7 @@ services:
    restart: always
    labels:
      - traefik.enable=true
-      - traefik.http.routers.sabnzbd.rule=PathPrefix(`/sabnzbd`) # Simplified rule
+      - traefik.http.routers.sabnzbd.rule=(Host(`${HOSTNAME}`) && PathPrefix(`/sabnzbd`) || PathPrefix(`/sabnzbd`))
      - traefik.http.routers.sabnzbd.entrypoints=web
      - traefik.http.services.sabnzbd.loadbalancer.server.port=8080
      - homepage.group=Download
@@ -359,7 +358,7 @@ services:
      - PUID=${USER_ID}
      - PGID=${GROUP_ID}
      - TZ=${TIMEZONE}
-      - JELLYFIN_PublishedServerUrl=${TAILSCALE_HOSTNAME}.${TAILSCALE_TAILNET_DOMAIN}/jellyfin
+      - JELLYFIN_PublishedServerUrl=${HOSTNAME}/jellyfin
    volumes:
      - ${CONFIG_ROOT:-.}/jellyfin:/config:Z
      - ${DATA_ROOT}:/data:Z
@@ -373,7 +372,7 @@ services:
      retries: 10
    labels:
      - traefik.enable=true
-      - traefik.http.routers.jellyfin.rule=PathPrefix(`/jellyfin`)
+      - traefik.http.routers.jellyfin.rule=(Host(`${HOSTNAME}`) && PathPrefix(`/jellyfin`))
      - traefik.http.routers.jellyfin.entrypoints=web
      - traefik.http.services.jellyfin.loadbalancer.server.port=8096
      - homepage.group=Media
@@ -404,7 +403,7 @@ services:
      - traefik.http.middlewares.calibre-headers.headers.customRequestHeaders.X-Script-Name=/calibre
      - traefik.http.middlewares.calibre-stripprefixregex.stripPrefixRegex.regex=/calibre
      - traefik.http.routers.calibre.middlewares=calibre-headers,calibre-stripprefixregex
-      - traefik.http.routers.calibre.rule=Host(`${TAILSCALE_HOSTNAME}.${TAILSCALE_TAILNET_DOMAIN}`) && PathPrefix(`/calibre`)
+      - traefik.http.routers.calibre.rule=(Host(`${HOSTNAME}`) && PathPrefix(`/calibre`))
      - traefik.http.routers.calibre.entrypoints=web
      - traefik.http.services.calibre.loadbalancer.server.port=8083
      - homepage.group=Media
@@ -467,8 +466,7 @@ services:
      - HOMEPAGE_VAR_WEATHER_LONG=${HOMEPAGE_VAR_WEATHER_LONG}
      - HOMEPAGE_VAR_WEATHER_TIME=${TIMEZONE}
      - HOMEPAGE_VAR_WEATHER_UNIT=${HOMEPAGE_VAR_WEATHER_UNIT}
-      # Explicitly allow the hostname constructed from Tailscale variables
-      - HOMEPAGE_ALLOWED_HOSTS=${TAILSCALE_HOSTNAME}.${TAILSCALE_TAILNET_DOMAIN}
+      - HOMEPAGE_ALLOWED_HOSTS=${HOSTNAME}
    volumes:
      - ${CONFIG_ROOT:-.}/homepage:/app/config:Z
      - /var/run/docker.sock:/var/run/docker.sock:ro
@@ -478,10 +476,8 @@ services:
      [sh, -c, "cp -n /app/config/tpl/*.yaml /app/config && node server.js"]
    labels:
      - traefik.enable=true
-      # Change path to /home and use specific Tailscale host
-      - traefik.http.routers.homepage.rule=Host(`${TAILSCALE_HOSTNAME}.${TAILSCALE_TAILNET_DOMAIN}`) && PathPrefix(`/home`)
+      - traefik.http.routers.homepage.rule=(Host(`${HOSTNAME}`) && PathPrefix(`/`))
      - traefik.http.routers.homepage.entrypoints=web
-      # Authelia middleware will be added in a later commit
      - traefik.http.services.homepage.loadbalancer.server.port=3000
  watchtower:
    image: ghcr.io/containrrr/watchtower:latest
@@ -518,8 +514,6 @@ services:
    cap_add:
      - NET_ADMIN
      - NET_RAW
-    extra_hosts: # Add this section
-      - host.docker.internal:172.17.0.1
    restart: always
    command:
      - /bin/sh
@@ -545,12 +539,12 @@ services:
        # --- Start Tailscale Funnel/Serve ---
        # Check the ENABLE_FUNNEL_HTTPS variable
        if [ "${ENABLE_FUNNEL_HTTPS}" = "true" ]; then
-          echo "ENABLE_FUNNEL_HTTPS is true. Setting up Funnel -> http://localhost:80..."
-          tailscale funnel --bg http://localhost:80
+          echo "ENABLE_FUNNEL_HTTPS is true. Setting up Funnel -> http://traefik:80..."
+          tailscale funnel --bg http://traefik:80
          echo "Tailscale Funnel configured."
        else
-          echo "ENABLE_FUNNEL_HTTPS is false. Setting up Serve -> http://localhost:80..."
-          tailscale serve --bg http://localhost:80
+          echo "ENABLE_FUNNEL_HTTPS is false. Setting up Serve -> http://traefik:80..."
+          tailscale serve --bg http://traefik:80
          echo "Tailscale Serve configured."
        fi
        # --- End Tailscale Funnel/Serve ---