From 38919d560d927a795f331d611a17145c387adf4b Mon Sep 17 00:00:00 2001 From: Jack Spiering <46534141+jackspiering@users.noreply.github.com> Date: Wed, 7 Oct 2026 19:17:11 +0200 Subject: [PATCH 1/2] All services: standardize the service READMEs Give every service README the same headings in the same order: At a glance, Before you start, Deviations from the standard setup, First run, and Links, with Configuration, Troubleshooting, and Upgrading as optional sections. - Describe the shared sidecar setup once in documentation/standard-setup.md, so that a service README only lists what differs. - Move the port 53 guide to documentation/free-up-port-53.md. - Reduce the template README to the headings and placeholders, and move the instructions for contributors to CONTRIBUTING.md. - Rewrite all 122 service READMEs. Remove feature lists and the repeated sidecar explanation, and keep the service-specific notes. --- CONTRIBUTING.md | 36 ++++- README.md | 2 + documentation/free-up-port-53.md | 40 ++++++ documentation/standard-setup.md | 53 +++++++ services/actual-budget/README.md | 37 ++--- services/adguardhome-sync/README.md | 47 +++++-- services/adguardhome/README.md | 74 +++++----- services/affine/README.md | 52 +++---- services/anchor/README.md | 39 +++--- services/arcane/README.md | 45 +++--- services/artisttrackarr/README.md | 78 +++++------ services/audiobookshelf/README.md | 37 ++++- services/bazarr/README.md | 41 +++++- services/bentopdf/README.md | 40 +++--- services/beszel-agent/README.md | 39 +++++- services/beszel-hub/README.md | 34 ++++- services/booklore/README.md | 37 ++++- services/caddy/README.md | 52 +++++-- services/changedetection/README.md | 32 ++++- services/clipcascade/README.md | 40 ++++-- services/coder/README.md | 54 +++++--- services/configarr/README.md | 51 ++++--- services/convertx/README.md | 31 ++++- services/copyparty/README.md | 43 +++--- services/cyberchef/README.md | 32 ++++- services/ddns-updater/README.md | 44 +++--- services/dockge/README.md | 40 ++++-- services/dockhand/README.md | 44 +++--- services/docmost/README.md | 54 +++++--- services/donetick/README.md | 38 ++--- services/dozzle/README.md | 38 ++++- services/dumbdo/README.md | 34 +++-- services/eigenfocus/README.md | 36 +++-- services/espocrm/README.md | 46 +++++-- services/excalidraw/README.md | 32 ++++- services/filebrowser/README.md | 57 ++++---- services/flaresolverr/README.md | 34 ++++- services/flatnotes/README.md | 38 +++-- services/forgejo/README.md | 47 ++++--- services/formbricks/README.md | 57 ++++---- services/fossflow/README.md | 39 ++++-- services/freshrss/README.md | 64 +++++---- services/frigate/README.md | 57 ++++---- services/ghost/README.md | 41 ++++-- services/gitea/README.md | 44 ++++-- services/gitsave/README.md | 40 ++++-- services/glance/README.md | 36 ++++- services/gokapi/README.md | 33 ++++- services/gotify/README.md | 38 +++-- services/grampsweb/README.md | 45 ++++-- services/haptic/README.md | 35 +++-- services/hemmelig/README.md | 45 +++--- services/homarr/README.md | 38 +++-- services/home-assistant/README.md | 60 ++++---- services/homebox/README.md | 72 ++++------ services/homepage/README.md | 33 ++++- services/hytale/README.md | 45 ++++-- services/immich/README.md | 77 ++++++++--- services/isley/README.md | 40 +++--- services/it-tools/README.md | 31 ++++- services/jellyfin/README.md | 37 ++++- services/kaneo/README.md | 45 ++++-- services/karakeep/README.md | 77 ++++++----- services/kavita/README.md | 40 +++--- services/kitchenowl/README.md | 67 ++++----- services/languagetool/README.md | 73 ++++++---- services/linkding/README.md | 44 ++++-- services/lube-logger/README.md | 39 ++++-- services/mailpit/README.md | 85 +++++------- services/mattermost/README.md | 62 +++++---- services/mealie/README.md | 39 ++++-- services/memos/README.md | 33 +++-- services/metube/README.md | 32 ++++- services/minecraft/README.md | 95 +++++-------- services/miniflux/README.md | 45 +++--- services/miniqr/README.md | 36 +++-- services/nanote/README.md | 35 +++-- services/navidrome/README.md | 40 ++++-- services/nessus/README.md | 39 +++--- services/netbox/README.md | 59 ++++++-- services/newwallpaperwhodis/README.md | 45 +++--- services/next-explorer/README.md | 40 +++++- services/nodered/README.md | 37 +++-- services/ntfy/README.md | 64 ++++++++- services/ollama/README.md | 115 +++++----------- services/open-webui/README.md | 62 +++++---- services/paperless/README.md | 47 ++++++- services/picard/README.md | 48 +++---- services/pihole/README.md | 83 ++++++----- services/pingvin-share/README.md | 34 ++++- services/plex/README.md | 36 ++++- services/pocket-id/README.md | 62 ++++----- services/portainer/README.md | 39 +++++- services/portracker/README.md | 37 +++-- services/posterizarr/README.md | 61 ++++---- services/prowlarr/README.md | 35 ++++- services/qbittorrent/README.md | 41 +++++- services/radarr/README.md | 36 +++-- services/radicale/README.md | 76 ++++------ services/recyclarr/README.md | 63 ++++----- services/resilio-sync/README.md | 34 ++++- services/rustdesk-server/README.md | 49 +++++-- services/seafile/README.md | 63 ++++++--- services/searxng/README.md | 44 ++++-- services/seerr/README.md | 38 +++-- services/slink/README.md | 44 +++++- services/sonarr/README.md | 36 +++-- services/speedtest-tracker/README.md | 44 +++--- services/stirlingpdf/README.md | 33 ++++- services/subtrackr/README.md | 37 +++-- services/sure/README.md | 130 +++++++----------- services/swingmx/README.md | 43 +++--- .../tailscale-app-connector-node/README.md | 42 ++++-- services/tailscale-exit-node/README.md | 41 ++++-- .../tailscale-subnet-router-node/README.md | 42 ++++-- services/tandoor/README.md | 46 +++++-- services/tautulli/README.md | 38 ++++- services/technitium/README.md | 45 +++++- services/tracktor/README.md | 47 +++---- services/traefik/README.md | 44 ++++-- services/transmute/README.md | 43 +++--- services/uptime-kuma/README.md | 34 ++++- services/vaultwarden/README.md | 40 +++++- services/vikunja/README.md | 49 ++++--- services/wallos/README.md | 37 +++-- services/xwiki/README.md | 42 ++++-- templates/service-template/README.md | 37 ++--- 127 files changed, 3772 insertions(+), 2151 deletions(-) create mode 100644 documentation/free-up-port-53.md create mode 100644 documentation/standard-setup.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 78e516a8..889d1afd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -72,8 +72,40 @@ Thanks for helping improve these Tailscale sidecar examples. 6. Complete the service README. - Document prerequisites, persistent paths, setup steps, ports, Tailnet access, - and service-specific exceptions. Link to the upstream documentation. + Every service README uses the headings of the template, in the same order. + Do not rename them and do not add others, so that every service reads the + same way. Replace the placeholders in capitals. + + - **Introduction.** Say what the service does in one or two sentences and + link to the upstream project. Leave feature lists to upstream. + - **At a glance.** Give the Tailnet address, the port that Tailscale Serve + forwards to, the image, and the data paths on the host. Add a row for + each further port that users connect to, such as DNS or SMTP. + - **Before you start.** List only what the Quick Start does not cover: + values that must change in `.env`, secrets to generate, folders to + create, and required host groups or devices. + - **Deviations from the standard setup.** List every difference from + [the standard setup](documentation/standard-setup.md) and give the + reason. Examples are extra containers, published host ports, a changed + or removed Serve configuration, DNS settings, and added capabilities. + - **First run.** Describe what the user does after the first start, such + as creating the first account or finding a generated password. + - **Links.** Link to the upstream documentation and source code. + + When a section has nothing to report, keep the heading and the sentence + from the template. A reader can then tell that the service follows the + standard setup, and that the section was not forgotten. + + Add these optional sections between "First run" and "Links" when the + service needs them, in this order: + + - **Configuration.** Optional settings that users commonly change. + - **Troubleshooting.** Known errors and their solutions. + - **Upgrading.** Steps for users of an older version of the stack. + + State only what you confirmed in the Compose file, the upstream + documentation, or a running stack. Put guidance that applies to more than + one service in `documentation/` and link to it. 7. Add the service to the correct category in the root `README.md`. diff --git a/README.md b/README.md index 558dad95..58a4a350 100644 --- a/README.md +++ b/README.md @@ -40,6 +40,8 @@ ScaleTail provides ready-to-run [Docker Compose](https://docs.docker.com/compose docker compose up -d ``` +Every stack starts from the same [standard setup](documentation/standard-setup.md), which explains the containers, the Tailnet address, and the settings in `.env`. + ## Table of Contents - [ScaleTail - Secure Self-Hosting Made Simple](#scaletail---secure-self-hosting-made-simple) diff --git a/documentation/free-up-port-53.md b/documentation/free-up-port-53.md new file mode 100644 index 00000000..dd088bfd --- /dev/null +++ b/documentation/free-up-port-53.md @@ -0,0 +1,40 @@ +# Free up port 53 on the Docker host + +A DNS service such as Pi-hole or AdGuard Home needs port 53. This page applies only when you publish port 53 on the Docker host, for example to offer DNS to your local network. A stack that is reachable over your Tailnet only does not need it. + +## Why port 53 is in use + +On Debian-based systems that use `systemd-resolved`, such as Ubuntu Server 22.04 and 24.04, a DNS stub listener runs by default. It listens on `127.0.0.53:53` and answers DNS queries from local applications. A container that publishes port 53 on all host addresses then fails to start, because the port is already taken. + +The `DNSStubListener` option in `/etc/systemd/resolved.conf` controls this listener: + +- `DNSStubListener=yes`: `systemd-resolved` listens on `127.0.0.53:53`. This is the default. +- `DNSStubListener=no`: `systemd-resolved` does not listen on port 53, so another DNS service can use it. + +## Steps + +1. Open the configuration file: + + ```bash + sudo nano /etc/systemd/resolved.conf + ``` + +2. Find the line `#DNSStubListener=yes` and change it to: + + ```ini + DNSStubListener=no + ``` + +3. Restart the service: + + ```bash + sudo systemctl restart systemd-resolved + ``` + +4. Check that port 53 is free: + + ```bash + sudo ss -tuln | grep ':53 ' + ``` + + The command prints nothing when no process listens on port 53. diff --git a/documentation/standard-setup.md b/documentation/standard-setup.md new file mode 100644 index 00000000..ad156413 --- /dev/null +++ b/documentation/standard-setup.md @@ -0,0 +1,53 @@ +# The standard ScaleTail setup + +Every service in this repository starts from the same [template](../templates/service-template/). This page describes that shared setup once. The README of a service only lists what differs, under the heading "Deviations from the standard setup". + +## Containers + +Each stack runs two containers that share one network namespace. + +| Compose service | Container name | Purpose | +| --------------- | ----------------------- | -------------------------------------------------------------------- | +| `tailscale` | `tailscale-` | Joins your Tailnet as a device named after `SERVICE` in `.env`. | +| `application` | `app-` | Runs the service and uses the network of the `tailscale` container. | + +The application uses `network_mode: service:tailscale` and starts only after the `tailscale` container reports healthy. + +## Tailnet access + +- **Web interface.** [Tailscale Serve](https://tailscale.com/kb/1312/serve) publishes the web interface at `https://..ts.net` and forwards it to the internal port of the application. `` is the value of `SERVICE` and `` is your [Tailnet name](https://tailscale.com/kb/1217/tailnet-name). +- **Requirements.** Your Tailnet needs [MagicDNS](https://tailscale.com/kb/1081/magicdns) and [HTTPS certificates](https://tailscale.com/kb/1153/enabling-https) enabled. The first request can take up to a minute, because Tailscale requests the certificate at that moment. +- **Tailnet only.** Tailscale Funnel is disabled, so the service is not reachable from the public internet. +- **Other ports.** Any other port the application listens on is reachable at the Tailscale IP address of the device, when your Tailnet policy allows it. +- **No host ports.** The stack publishes no ports on the Docker host. To reach the service from your local network as well, uncomment the `ports` block of the `tailscale` service. + +## Settings in `.env` + +| Variable | Purpose | +| ------------- | -------------------------------------------------------------------------------------------- | +| `SERVICE` | Name of the Tailnet device, the containers, and the data folder. | +| `IMAGE_URL` | Image of the application. | +| `SERVICEPORT` | Port used by the optional `ports` block. The port for Tailscale Serve is set in `compose.yaml`. | +| `DNS_SERVER` | DNS server used by the optional `dns` block. | +| `TS_AUTHKEY` | Your Tailscale auth key. Only needed for the first start. | +| `TZ` | Time zone, passed to the application when its image supports it. | + +## Data + +All data stays in the service directory, next to `compose.yaml`. + +| Path | Content | +| ------------------- | ----------------------------------------- | +| `./config` | Tailscale configuration files. | +| `./ts/state` | Tailscale state, including the device key. | +| `./-data/` | Data of the application. | + +Keep `./ts/state` when you recreate the stack. Without it, the device joins your Tailnet again as a new device. + +## DNS + +The containers use Docker's DNS by default, so the application can reach other containers in the same stack by their Compose service name. It cannot resolve MagicDNS names of other Tailnet devices. + +- To reach another Tailnet device from the application, use its Tailscale IP address. +- To use MagicDNS names instead, uncomment `TS_ACCEPT_DNS=true`. This replaces Docker's DNS, so Compose service names no longer resolve. Do not use it in a stack where the application depends on other containers by name. +- If name resolution fails in general, uncomment the `dns` block to use the server from `DNS_SERVER`. diff --git a/services/actual-budget/README.md b/services/actual-budget/README.md index 93282d00..c8fbb178 100644 --- a/services/actual-budget/README.md +++ b/services/actual-budget/README.md @@ -1,28 +1,31 @@ -# Actual Budget with Tailscale Sidecar Configuration +# Actual Budget -This Docker Compose configuration sets up **Actual Budget** with a Tailscale sidecar container, enabling secure and private access to your personal finance app over your Tailnet. With this setup, your budgeting data stays fully private and is only accessible from trusted devices, without exposing anything to the public internet. +[Actual Budget](https://actualbudget.org/) is a personal finance app for budgeting. You track your accounts and spending and plan your budget, and your data stays on your own server. -## Actual Budget +This stack runs Actual Budget with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Actual Budget](https://github.com/actualbudget/actual) is an open-source, self-hosted personal finance and budgeting app focused on privacy and control. It serves as a modern alternative to tools like YNAB, allowing you to track spending, manage accounts, and plan budgets while retaining full ownership of your financial data. +## At a glance -When paired with Tailscale, Actual Budget becomes accessible across your devices through your secure Tailnet, eliminating the need for public exposure or complex reverse proxy configurations. +| Item | Value | +| ------------- | ---------------------------------------- | +| Web interface | `https://actual-budget..ts.net` | +| Service port | `5006` | +| Image | `docker.io/actualbudget/actual-server` | +| Data | `./actual-budget-data` | -## Configuration Overview +## Before you start -In this setup, the `tailscale-actual` service runs Tailscale, which manages secure networking for Actual Budget. The `actual` service uses the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This ensures the application is only reachable over your Tailnet unless you explicitly expose ports. +Nothing beyond the [Quick Start](../../README.md#quick-start). -## Key Features +## Deviations from the standard setup -- Self-hosted personal budgeting platform -- Privacy-first approach with full data ownership -- Sync across devices without relying on third-party cloud services -- Transaction tracking, budgeting, and reporting -- Secure Tailnet-only access via Tailscale +None. -## Files to check +## First run -Please check the following contents for validity as some variables need to be defined upfront. +Open the web interface and set a password for the server. Then create a budget file or import an existing one. -- `.env` - - Required: `TS_AUTHKEY` +## Links + +- [Actual Budget documentation](https://actualbudget.org/docs/) +- [Actual Budget source code](https://github.com/actualbudget/actual) diff --git a/services/adguardhome-sync/README.md b/services/adguardhome-sync/README.md index 0a3c2f80..528ac4f2 100644 --- a/services/adguardhome-sync/README.md +++ b/services/adguardhome-sync/README.md @@ -1,19 +1,42 @@ -# AdGuardHome Sync with Tailscale Sidecar Configuration +# AdGuard Home Sync -This Docker Compose configuration sets up **[AdGuardHome Sync](https://github.com/bakito/adguardhome-sync)** with Tailscale as a sidecar container to securely synchronize your AdGuard Home instances over a private Tailscale network. By integrating Tailscale, you ensure that configuration data is transmitted securely between nodes and accessible only to authorized devices in your private network. +[AdGuard Home Sync](https://github.com/bakito/adguardhome-sync) copies the configuration of one AdGuard Home instance to one or more replicas, including filters, rewrites, clients, and DNS settings. -## AdGuardHome Sync +This stack runs AdGuard Home Sync with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[AdGuardHome Sync](https://github.com/bakito/adguardhome-sync) is a **lightweight tool for synchronizing configuration between multiple AdGuard Home servers**. It supports syncing DNS settings, clients, rules, rewrites, and more—making it ideal for managing AdGuard Home across multiple networks or locations. Whether you're managing redundant setups or simply keeping home and remote deployments in sync, this tool helps you maintain consistency and saves time. +## At a glance -## Key Features +| Item | Value | +| ------------- | ------------------------------------------------------------------------------- | +| Web interface | None | +| Service port | `8080` on the Tailscale IP address of `adguardhome-sync` (API of the sync tool) | +| Image | `ghcr.io/bakito/adguardhome-sync` | +| Data | None | -* **Multi-Node Syncing** – Keep multiple AdGuard Home instances in sync effortlessly. -* **Granular Configuration** – Choose which parts of the configuration to sync (rules, clients, rewrites, etc.). -* **Push or Pull Modes** – Use a master-push or node-pull strategy to fit your setup. -* **Self-Hosted** – Fully local, no third-party service required. -* **Secure Access with Tailscale** – Safely connect and sync instances across private networks using Tailscale. +## Before you start -## Configuration Overview +Replace the sample values in the `environment` block of `compose.yaml`: -In this setup, the `tailscale-adguardhome-sync` service runs Tailscale, which manages secure networking for the AdGuardHome Sync service. The `adguardhome-sync` container uses the Tailscale network stack via Docker’s `network_mode: service:tailscale` configuration. This ensures that all sync communication is confined to your private Tailscale network, preventing exposure to the public internet. +- **`ORIGIN_URL`, `ORIGIN_USERNAME`, `ORIGIN_PASSWORD`.** The AdGuard Home instance to copy from. +- **`REPLICA1_URL`, `REPLICA1_USERNAME`, `REPLICA1_PASSWORD`.** The instance to copy to. +- **`CRON`.** The schedule. The sample value runs a sync every minute. + +To reach an AdGuard Home instance on your Tailnet, see the [DNS section of the standard setup](../../documentation/standard-setup.md#dns). + +## Deviations from the standard setup + +- **No Tailscale Serve.** The stack has no Serve configuration. The tool only makes outgoing connections to your AdGuard Home instances. +- **Start command.** The stack starts the tool with the `run` command. +- **No data folder.** The tool stores nothing on disk. All settings are in `compose.yaml`. + +## First run + +Check the log to see whether the sync works: + +```bash +docker logs app-adguardhome-sync +``` + +## Links + +- [AdGuard Home Sync documentation and source code](https://github.com/bakito/adguardhome-sync) diff --git a/services/adguardhome/README.md b/services/adguardhome/README.md index b9f36dd3..3f87de84 100644 --- a/services/adguardhome/README.md +++ b/services/adguardhome/README.md @@ -1,62 +1,54 @@ -# AdGuard Home with Tailscale Sidecar Configuration +# AdGuard Home -This Docker Compose configuration sets up [AdGuard Home](https://github.com/AdguardTeam/AdGuardHome) with Tailscale as a sidecar container to securely route DNS traffic over a private Tailscale network. By using Tailscale in a sidecar configuration, you can enhance the security and privacy of your DNS queries, ensuring that they are only accessible within your Tailscale network. +[AdGuard Home](https://github.com/AdguardTeam/AdGuardHome) is a DNS server that blocks advertisements and trackers for every device that uses it. -## AdGuard Home +This stack runs AdGuard Home with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[AdGuard Home](https://github.com/AdguardTeam/AdGuardHome) is a network-wide software that blocks ads and trackers. It provides a powerful DNS filtering solution that can protect all devices on your network. This configuration allows AdGuard Home to be used in combination with Tailscale, providing a secure and private network for DNS queries. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | ------------------------------------------------------------------------------------------- | +| Web interface | `https://adguardhome..ts.net` (after the setup wizard) | +| Setup wizard | `http://:3000` (first start only) | +| Service port | `80` | +| DNS | Port `53` (TCP and UDP) on the Tailscale IP address of `adguardhome` and on the Docker host | +| Image | `adguard/adguardhome` | +| Data | `./adguardhome-data/configdir` (configuration) | +| | `./adguardhome-data/workdir` (filters, statistics, and query log) | -In this setup, the `tailscale-adguardhome` service runs Tailscale, which manages secure networking for the AdGuard Home service. The `adguardhome` service uses the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This setup ensures that AdGuard Home's DNS service is only accessible through the Tailscale network (or local as well, if preferred). +## Before you start -## Binding to your local host machine? Port 53 - DNSStubListener +The stack publishes port `53` on the Docker host. On a host that runs `systemd-resolved`, this port is in use. See [Free up port 53 on the Docker host](../../documentation/free-up-port-53.md). -In Debian (e.g. Ubuntu Server 22.04.x / 24.04.x) systems, particularly when using systemd-resolved for DNS resolution, a DNS stub listener is employed by default to provide local DNS resolution through the loopback address (localhost). This stub listener binds to port 53 on the local interface 127.0.0.53, allowing local applications to send DNS queries to this address for resolution. +## Deviations from the standard setup -### What is DNSStubListener? +- **Published host ports.** The `ports` block is active and publishes DNS on port `53` (TCP and UDP) of the Docker host. Devices in your local network can therefore use AdGuard Home without Tailscale. +- **Setup wizard on port `3000`.** At the first start, AdGuard Home only listens on port `3000`. Tailscale Serve forwards to port `80`, so the web interface is not available at the Tailnet address until you finish the wizard. +- **DNS does not use Tailscale Serve.** Serve only handles the web interface. AdGuard Home listens for DNS queries on port `53` of the Tailscale IP address of the device. -`DNSStubListener` is a configuration option in the `/etc/systemd/resolved.conf` file that controls whether the `systemd-resolved` service will listen for DNS queries on the loopback address (127.0.0.53) over port 53. +## First run -- **DNSStubListener=yes**: When this option is enabled, `systemd-resolved` binds to `127.0.0.53:53`. This allows the system to use `systemd-resolved` as a local DNS resolver for local DNS queries. - -- **DNSStubListener=no**: Disabling the stub listener prevents `systemd-resolved` from binding to port 53 on the local interface, freeing up this port for other DNS services or applications that require direct control over port 53. - -### Why Change `DNSStubListener` to `no`? - -In certain scenarios, such as when running a local DNS server (e.g., AdguardHome, PiHole, BIND, Unbound, or Dnsmasq) or any other application that requires exclusive access to port 53 on all interfaces, `systemd-resolved`'s binding to the local DNS port can cause conflicts. For example, if you plan to run your own DNS server on the same machine, that service needs to bind to port 53 globally, including the loopback interface. With `systemd-resolved` already occupying this port, the new DNS service would fail to start or function properly. - -To resolve this issue, you need to disable `systemd-resolved` from binding to port 53 by setting `DNSStubListener=no` in the `/etc/systemd/resolved.conf` file. - -### Steps to Free Up Port 53 - -1. **Open the configuration file**: +1. Find the Tailscale IP address of the device: ```bash - sudo nano /etc/systemd/resolved.conf + docker exec tailscale-adguardhome tailscale ip -4 ``` -2. **Modify the `DNSStubListener` setting**: +2. Open `http://:3000` and follow the setup wizard. Keep port `80` for the web interface and port `53` for the DNS server, and create the administrator account. +3. Open the web interface at `https://adguardhome..ts.net` and log in. - Find the line containing `#DNSStubListener=yes` (it might be commented out by default) and change it to: +## Configuration - ```bash - DNSStubListener=no - ``` - -3. **Restart the `systemd-resolved` service**: - After saving the changes, restart the service for the changes to take effect: +### Use AdGuard Home as the DNS server of your Tailnet - ```bash - sudo systemctl restart systemd-resolved - ``` +In the Tailscale admin console, open the **DNS** page. Add the Tailscale IP address of the `adguardhome` device as a custom nameserver and enable **Override DNS servers**. -4. **Verify Port 53 is Free**: +### Use AdGuard Home in your local network - You can check that port 53 is no longer bound by `systemd-resolved` by running: +Point your devices or your router at the IP address of the Docker host as DNS server. - ```bash - sudo netstat -tuln | grep :53 - ``` +## Links -If the configuration was successful, no process should be listed as using port 53 on the loopback interface. +- [AdGuard Home wiki](https://github.com/AdguardTeam/AdGuardHome/wiki) +- [AdGuard Home Docker image](https://hub.docker.com/r/adguard/adguardhome) +- [AdGuard Home source code](https://github.com/AdguardTeam/AdGuardHome) diff --git a/services/affine/README.md b/services/affine/README.md index 3e066b19..bf652986 100644 --- a/services/affine/README.md +++ b/services/affine/README.md @@ -1,35 +1,41 @@ -# AFFiNE with Tailscale Sidecar Configuration +# AFFiNE -This Docker Compose configuration sets up **AFFiNE** with a Tailscale sidecar container, enabling secure, private access to your workspace over your Tailnet. With this setup, your AFFiNE instance remains **private and accessible only from authorized devices on your Tailnet**, keeping your notes, documents, and collaborative content away from the public internet. +[AFFiNE](https://affine.pro/) is a workspace that combines documents, whiteboards, and databases. It is an open-source alternative to tools such as Notion and Miro. -## AFFiNE +This stack runs AFFiNE with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[**AFFiNE**](https://github.com/toeverything/affine) is an open-source, privacy-focused workspace that combines **documents, whiteboards, and databases** into a single platform. It is often described as an alternative to tools like Notion and Miro, giving individuals and teams a flexible environment for writing, planning, organizing, and collaborating. +## At a glance -AFFiNE is designed around modern knowledge work, blending structured content and visual collaboration while remaining self-hostable and open-source. That makes it a strong fit for users who want full ownership of their data and workflows. +| Item | Value | +| ------------- | ----------------------------------- | +| Web interface | `https://affine..ts.net` | +| Service port | `3010` | +| Images | `ghcr.io/toeverything/affine` | +| | `pgvector/pgvector:pg16` | +| | `redis` | +| Data | `./affine-storage` (uploaded files) | +| | `./affine-config` (configuration) | +| | `./postgres` (PostgreSQL database) | -## Key Features +## Before you start -- **Unified workspace** for docs, whiteboards, and knowledge organization -- **Open-source and self-hostable** for full control over your data -- **Privacy-focused design** without dependence on proprietary SaaS platforms -- **Collaborative editing** for teams and shared projects -- **Modern block-based editor** for flexible content creation -- **Visual thinking tools** with integrated whiteboard-style workflows -- **Notion and Miro alternative** in a single platform +Set these values in `.env`: -## Configuration Overview +- **`AFFINE_SERVER_EXTERNAL_URL`.** The address of the web interface, `https://affine..ts.net`. AFFiNE does not start with the sample value, because the `affine_migration` container fails. +- **`DB_PASSWORD`.** The password of the database. The default is `affine`. -In this setup, the `tailscale-affine` service runs Tailscale and handles secure networking for the stack. The `affine` service shares the Tailscale container's network namespace using Docker's `network_mode: service:tailscale` configuration. This means AFFiNE is reachable through your Tailnet without exposing it directly to the public internet. +## Deviations from the standard setup -This approach provides a secure and simple way to self-host AFFiNE privately, whether for personal note-taking, team collaboration, or internal documentation. +- **Extra containers.** The stack runs `postgres`, `redis`, and `affine_migration`. The migration container prepares the database and then exits. All three use the default Compose network, and AFFiNE reaches them by their service name through Docker's DNS. Keep `TS_ACCEPT_DNS` disabled, because MagicDNS cannot resolve these names. +- **Image version.** `AFFINE_REVISION` in `.env` selects the version of the AFFiNE image. +- **Data folders.** The data is in `./affine-storage`, `./affine-config`, and `./postgres`, not in a `./affine-data` folder. +- **The containers read the whole `.env` file.** The `application` and `affine_migration` containers load `.env` through `env_file`. Every variable in that file, including `TS_AUTHKEY`, is therefore present in their environment. -## Typical Use Cases +## First run -This setup is especially useful for: +Open the web interface. AFFiNE sends you to its setup page, where you create the administrator account. -- Personal knowledge management -- Team wikis and internal documentation -- Project planning and collaborative workspaces -- Visual brainstorming and whiteboarding -- Private alternatives to cloud-based productivity suites +## Links + +- [AFFiNE self-hosting documentation](https://docs.affine.pro/self-host-affine) +- [AFFiNE source code](https://github.com/toeverything/affine) diff --git a/services/anchor/README.md b/services/anchor/README.md index d16c77b3..18ebb44e 100644 --- a/services/anchor/README.md +++ b/services/anchor/README.md @@ -1,32 +1,31 @@ -# Anchor with Tailscale Sidecar Configuration +# Anchor -This Docker Compose configuration sets up [Anchor](https://github.com/ZhFahim/anchor) with Tailscale as a sidecar container so your notes stay reachable only over your Tailnet instead of being exposed to the public internet. +[Anchor](https://github.com/ZhFahim/anchor) is a note-taking application for the web and mobile devices. It works offline and synchronises your notes when the device is online again. -## Anchor +This stack runs Anchor with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Anchor](https://github.com/ZhFahim/anchor) is an offline-first, self-hostable note-taking application focused on speed, privacy, and reliability across web and mobile. It stores notes locally, syncs changes across devices when online, and supports features like rich text editing, attachments, tagging, sharing, and optional OIDC authentication. Pairing Anchor with Tailscale is a strong fit when you want private access to your notes from anywhere without putting the app behind a public reverse proxy. +## At a glance -## Key Features +| Item | Value | +| ------------- | --------------------------------------------- | +| Web interface | `https://anchor..ts.net` | +| Service port | `3000` | +| Image | `ghcr.io/zhfahim/anchor` | +| Data | `./anchor-data` (database and uploaded files) | -- Offline-first note-taking with automatic sync when devices reconnect -- Clean, fast web and mobile interface with rich text editing -- Support for attachments, tags, and note organization -- Optional sharing capabilities for collaboration -- OIDC authentication support (Authelia, Authentik, Keycloak, Pocket ID, etc.) -- Self-hosted and privacy-focused with full data ownership -- Works seamlessly with Tailscale for private, secure remote access +## Before you start -## Configuration Overview +Nothing beyond the [Quick Start](../../README.md#quick-start). -In this setup, the `tailscale-anchor` service runs Tailscale and manages secure networking for Anchor. The `anchor` service shares that network stack via Docker's `network_mode: service:tailscale` configuration, which keeps the app private to your Tailnet unless you intentionally add host port mappings or funnel it through another public entrypoint. +## Deviations from the standard setup -## Upstream documentation +None. -- [Anchor GitHub repository](https://github.com/ZhFahim/anchor) -- [Anchor OIDC configuration](https://github.com/ZhFahim/anchor#oidc-authentication) +## First run -## Files to check +Open the web interface and register the first account. -Please check the following contents for validity as some variables need to be defined upfront. +## Links -- `.env` // Main variable `TS_AUTHKEY` +- [Anchor documentation and source code](https://github.com/ZhFahim/anchor) +- [Anchor OIDC configuration](https://github.com/ZhFahim/anchor#oidc-authentication) diff --git a/services/arcane/README.md b/services/arcane/README.md index c086f358..452beec9 100644 --- a/services/arcane/README.md +++ b/services/arcane/README.md @@ -1,33 +1,34 @@ -# Arcane with Tailscale Sidecar Configuration +# Arcane -This Docker Compose configuration sets up **Arcane** with a Tailscale sidecar container, enabling secure access to your self-hosted Docker management interface over your private Tailscale network. With this setup, your Arcane instance remains **private and accessible only from authorized devices on your Tailnet**, keeping your Docker environment and operations shielded from public exposure. +[Arcane](https://getarcane.app/) is a web interface to manage Docker. You manage containers, images, networks, volumes, and Compose projects without the command line. -## Arcane +This stack runs Arcane with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[**Arcane**](https://getarcane.app/docs) is an open-source, self-hosted platform for **Docker container and Compose stack management** with a modern web interface. It allows users to manage containers, images, networks, volumes, remote environments, and projects—all without needing to rely on the Docker CLI. Arcane makes container operations approachable while providing powerful features for both homelab and production use. +## At a glance -## Key Features +| Item | Value | +| ------------- | ------------------------------------- | +| Web interface | `https://arcane..ts.net` | +| Service port | `3552` | +| Image | `ghcr.io/getarcaneapp/arcane` | +| Data | `./arcane-data` (application data) | +| | `./opt/dockerdata` (Compose projects) | -* 🐳 **Containers** – Start, stop, inspect, and monitor containers from a unified web UI. -* 📦 **Images** – List, pull, and manage container images. -* 🌐 **Networks** – View and create Docker networks with driver and subnet information. -* 🗂 **Projects** – Manage Docker Compose stacks as first-class resources, with a Projects UI and Git syncing. -* 🔄 **Remote Environments** – Control containers on other hosts using Arcane Agents. -* 💾 **Volumes** – Browse and manage Docker volumes. -* 🧰 **Templates & Guides** – Built-in support for templates and guides to streamline deployment patterns. -* 🔐 **Extensible Configuration** – Support for environment variables, OIDC single sign-on, notifications, HTTP proxies, and analytics. +## Before you start -## Configuration Overview +- **Set your Tailnet name.** Set `TAILNET_NAME` in `.env` to your Tailnet name, without `.ts.net`. `compose.yaml` builds the address of the application, `APP_URL`, from it. +- **Replace the secrets.** `ENCRYPTION_KEY` and `JWT_SECRET` in `compose.yaml` have a public sample value. Replace both with your own random values. -In this deployment, a **Tailscale sidecar container** (for example `tailscale-arcane`) runs the Tailscale client and joins your private Tailscale network. The main `arcane` service uses: +## Deviations from the standard setup -```plain -network_mode: service:tailscale -``` +- **Docker socket.** Arcane mounts `/var/run/docker.sock` with write access, which it needs to manage Docker. Everyone who can log in to Arcane has full control over the Docker host. +- **Data folders.** The Compose projects are in `./opt/dockerdata`, outside the `./arcane-data` folder. -This configuration routes all traffic through the Tailscale interface, ensuring that the Arcane web UI and API are accessible **only via your Tailscale network**. This provides a simple and secure way to access your Docker management console from all trusted devices while preventing public access to container controls. +## First run -## Default Credentials +Open the web interface and log in with username `arcane` and password `arcane-admin`. Arcane creates this account at the first start and asks you to change the password at the first login. -* Username: `arcane` -* Password: `arcane-admin` +## Links + +- [Arcane documentation](https://getarcane.app/docs) +- [Arcane source code](https://github.com/getarcaneapp/arcane) diff --git a/services/artisttrackarr/README.md b/services/artisttrackarr/README.md index 890ec199..488fb34c 100644 --- a/services/artisttrackarr/README.md +++ b/services/artisttrackarr/README.md @@ -1,60 +1,52 @@ -# ArtistTrackarr with Tailscale Sidecar Configuration +# ArtistTrackarr -This Docker Compose configuration sets up [ArtistTrackarr](https://github.com/crypt0rr/ArtistTrackarr) with Tailscale as a sidecar container, keeping the application securely reachable over your Tailnet without exposing it directly to the public internet. +[ArtistTrackarr](https://github.com/crypt0rr/ArtistTrackarr) watches MusicBrainz and, optionally, Spotify for new albums and EPs of the artists that your household follows. It sends notifications for announcements and release days. -## ArtistTrackarr +This stack runs ArtistTrackarr with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[ArtistTrackarr](https://github.com/crypt0rr/ArtistTrackarr) is a self-hosted household dashboard that monitors MusicBrainz and, optionally, Spotify for newly announced and released albums and EPs. It can send announcement and release-day notifications through Email, Discord, Telegram, ntfy, Gotify, generic webhooks, and other services supported by Shoutrrr. +## At a glance -Pairing ArtistTrackarr with Tailscale provides private access to its web interface from authorized Tailnet devices without requiring public port forwarding or a publicly accessible reverse proxy. +| Item | Value | +| ------------- | ------------------------------------------------- | +| Web interface | `https://artist-trackarr..ts.net` | +| Service port | `8080` | +| Image | `ghcr.io/crypt0rr/artist-trackarr` | +| Data | `./artist-trackarr-data` (database and cover art) | -## Configuration Overview +## Before you start -In this setup, the `tailscale-artist-trackarr` service runs Tailscale and manages secure networking for ArtistTrackarr. The `artist-trackarr` service uses the Tailscale container's network stack through Docker's `network_mode: service:tailscale` configuration. +1. Create the data folder yourself and make user `10001` its owner. Docker creates missing folders as user `root`, and the image runs as user and group `10001`. With the wrong owner, ArtistTrackarr cannot create its database. -ArtistTrackarr listens on port `8080`. Because both containers share the same network namespace, Tailscale Serve can forward traffic directly to `http://127.0.0.1:8080`. + ```bash + mkdir -p ./artist-trackarr-data + sudo chown -R 10001:10001 ./artist-trackarr-data + ``` -This keeps ArtistTrackarr Tailnet-only unless you intentionally publish its port on the Docker host. +2. Set these values in `.env`: -## Good to Know + - **`SETUP_TOKEN`, `APP_ENCRYPTION_KEY`, and `SESSION_SECRET`.** Three different random values of at least 32 characters each. + - **`MUSICBRAINZ_CONTACT`.** A real email address or project address. ArtistTrackarr sends it to MusicBrainz with each request. + - **`PUBLIC_URL`.** The address of the web interface, `https://artist-trackarr..ts.net`. -- **Container permissions:** The ArtistTrackarr image runs as UID and GID `10001`. When using a bind-mounted host directory for `/data`, create it before starting the stack and make it writable by UID and GID `10001`: +## Deviations from the standard setup - ```console - mkdir -p ./artist-trackarr-data - sudo chown -R 10001:10001 ./artist-trackarr-data - ``` +- **Device name.** `SERVICE` in `.env` is `artist-trackarr`, which differs from the name of this directory. +- **Secrets as files.** The stack passes `SETUP_TOKEN`, `APP_ENCRYPTION_KEY`, and `SESSION_SECRET` to the container as Docker secrets, not as environment variables. +- **Reduced privileges.** The `application` container drops all capabilities and sets `no-new-privileges`. - Incorrect ownership can prevent ArtistTrackarr from creating or opening its SQLite database. +## First run -- **Volumes:** ArtistTrackarr stores its SQLite database, cached Cover Art Archive artwork, and other persistent application data in `/data`. The upstream deployment uses the legacy-named `artist-tracker-data` Docker volume for compatibility with existing installations. +Open `https://artist-trackarr..ts.net/setup`, enter the value of `SETUP_TOKEN`, and create the first administrator. After that, the web interface shows the sign-in page. -- **Required application configuration:** Before starting ArtistTrackarr, define the following values: +## Configuration - - `SETUP_TOKEN` - - `APP_ENCRYPTION_KEY` - - `SESSION_SECRET` - - `MUSICBRAINZ_CONTACT` - - `PUBLIC_URL` +- **Polling interval.** `POLL_INTERVAL` in `.env` sets how often ArtistTrackarr checks for releases. The default is `6h`, and the application rejects values below one hour. +- **Spotify.** To use Spotify as an additional source, set `SPOTIFY_CLIENT_ID`, `SPOTIFY_CLIENT_SECRET`, and a two-letter `SPOTIFY_MARKET`, such as `NL`, in `.env`. You create the client in the [Spotify Developer Dashboard](https://developer.spotify.com/dashboard). +- **Client addresses.** Tailscale Serve is the reverse proxy of this stack. Set `TRUST_PROXY=true` in `.env` only if ArtistTrackarr should trust the client addresses that the proxy forwards. +- **Backups.** Stop the stack before you back up `./artist-trackarr-data`, so that the copy of the database is consistent. - `SETUP_TOKEN`, `APP_ENCRYPTION_KEY`, and `SESSION_SECRET` should each contain a random value of at least 32 characters. `MUSICBRAINZ_CONTACT` must contain a real email address or project URL because it is included in the MusicBrainz API User-Agent. +## Links -- **Public URL:** Set `PUBLIC_URL` to the HTTPS address through which users will access ArtistTrackarr over Tailscale, for example: - - ```env - PUBLIC_URL=https://artist-trackarr.example-tailnet.ts.net - ``` - -- **Polling interval:** The default `POLL_INTERVAL` is `6h`. Values below one hour are rejected by the application. - -- **Spotify integration:** Spotify integration is optional. Configure `SPOTIFY_CLIENT_ID`, `SPOTIFY_CLIENT_SECRET`, and an appropriate two-letter `SPOTIFY_MARKET`, such as `NL`, to enable Spotify-first artist discovery and an additional release-observation feed. - -- **Reverse-proxy handling:** Tailscale Serve acts as the HTTPS reverse proxy in this deployment. Set `TRUST_PROXY=true` only when ArtistTrackarr should trust forwarded client-address headers from the proxy. - -- **Backups:** Stop ArtistTrackarr before backing up its persistent `/data` directory or Docker volume to ensure a consistent SQLite backup. Database migrations run automatically when the application is upgraded. - -- **Official links:** - - [ArtistTrackarr repository](https://github.com/crypt0rr/ArtistTrackarr) - - [Shoutrrr documentation](https://containrrr.dev/shoutrrr/) - - [MusicBrainz](https://musicbrainz.org/) - - [Spotify Developer Dashboard](https://developer.spotify.com/dashboard) +- [ArtistTrackarr documentation and source code](https://github.com/crypt0rr/ArtistTrackarr) +- [Shoutrrr documentation](https://containrrr.dev/shoutrrr/), for the notification services +- [MusicBrainz](https://musicbrainz.org/) diff --git a/services/audiobookshelf/README.md b/services/audiobookshelf/README.md index 9ef2f84f..846b8402 100644 --- a/services/audiobookshelf/README.md +++ b/services/audiobookshelf/README.md @@ -1,11 +1,36 @@ -# Audiobookshelf with Tailscale Sidecar Configuration +# Audiobookshelf -This Docker Compose configuration sets up [Audiobookshelf](https://github.com/advplyr/audiobookshelf) with Tailscale as a sidecar container to securely access and manage your audiobook and podcast library over a private Tailscale network. By integrating Tailscale, you can ensure that your Audiobookshelf instance remains private and accessible only to devices within your Tailscale network. +[Audiobookshelf](https://www.audiobookshelf.org/) is a server for your audiobooks and podcasts. It streams them to the web player and the mobile apps and keeps your listening progress in sync. -## Audiobookshelf +This stack runs Audiobookshelf with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Audiobookshelf](https://github.com/advplyr/audiobookshelf) is an open-source self-hosted application for managing and streaming audiobooks and podcasts. It offers features like multi-user support, playback progress sync, a web player, and mobile app integrations, making it easy to organize and enjoy your audiobook and podcast collection from anywhere. By adding Tailscale, you can protect your library from unauthorized access while maintaining seamless and secure connectivity for all your devices. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | ----------------------------------------------------------------- | +| Web interface | `https://audiobookshelf..ts.net` | +| Service port | `80` | +| Image | `ghcr.io/advplyr/audiobookshelf` | +| Data | `./audiobookshelf-data/app/config` (configuration and database) | +| | `./audiobookshelf-data/app/metadata` (covers, cache, and backups) | +| | `./audiobookshelf-data/app/audiobooks` (audiobook library) | +| | `./audiobookshelf-data/app/podcasts` (podcast library) | -In this setup, the `tailscale-audiobookshelf` service runs Tailscale, which manages secure networking for the Audiobookshelf service. The `audiobookshelf` service uses the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This ensures that Audiobookshelf’s web interface and streaming capabilities are only accessible through the Tailscale network (or locally, if preferred), providing an extra layer of security and privacy for your personal audiobook and podcast collection. +## Before you start + +To use an existing collection, point the `/audiobooks` and `/podcasts` volumes in `compose.yaml` at your own folders. Otherwise the stack starts with empty folders in `./audiobookshelf-data`. + +## Deviations from the standard setup + +None. + +## First run + +Open the web interface and create the root user. Then add a library that points to `/audiobooks` or `/podcasts`. + +In the mobile apps, use `https://audiobookshelf..ts.net` as the server address. The device must be connected to your Tailnet. + +## Links + +- [Audiobookshelf documentation](https://www.audiobookshelf.org/docs) +- [Audiobookshelf source code](https://github.com/advplyr/audiobookshelf) diff --git a/services/bazarr/README.md b/services/bazarr/README.md index c966f62b..69757882 100644 --- a/services/bazarr/README.md +++ b/services/bazarr/README.md @@ -1,11 +1,40 @@ -# Bazarr with Tailscale Sidecar Configuration +# Bazarr -This Docker Compose configuration sets up [Bazarr](https://github.com/morpheus65535/bazarr) with Tailscale as a sidecar container to securely manage and access your subtitle management system over a private Tailscale network. By using Tailscale in a sidecar configuration, you can enhance the security and privacy of your Bazarr instance, ensuring that it is only accessible within your Tailscale network. +[Bazarr](https://www.bazarr.media/) downloads subtitles for the movies and series that Radarr and Sonarr manage. -## Bazarr +This stack runs Bazarr with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Bazarr](https://github.com/morpheus65535/bazarr) is an open-source, self-hosted application for managing and downloading subtitles for your movies and TV shows. It works in conjunction with other media managers like Sonarr and Radarr to automatically search for and download subtitles from various sources. This configuration leverages Tailscale to securely connect to your Bazarr instance, ensuring that your subtitle management interface is protected from unauthorized access and that your instance is accessible only via your private Tailscale network. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | --------------------------------------------------- | +| Web interface | `https://bazarr..ts.net` | +| Service port | `6767` | +| Image | `lscr.io/linuxserver/bazarr` | +| Data | `./bazarr-data/config` (configuration and database) | +| | `./bazarr-data/media/movies` (movie library) | +| | `./bazarr-data/media/tvseries` (series library) | -In this setup, the tailscale-bazarr service runs Tailscale, which manages secure networking for the Bazarr service. The bazarr service uses the Tailscale network stack via Docker's network_mode: service:tailscale configuration. This setup ensures that Bazarr’s web interface and API are only accessible through the Tailscale network (or locally, if preferred), providing an extra layer of security and privacy for your self-hosted subtitle manager. +## Before you start + +Point the `/movies` and `/tv` volumes in `compose.yaml` at the folders that Radarr and Sonarr use, because Bazarr stores the subtitles next to the video files. Docker creates missing folders as user `root`. The container runs as user and group `1000`, which need write access to both folders. + +## Deviations from the standard setup + +None. + +## First run + +Bazarr has no login by default. Open the web interface and go to **Settings**: + +1. Under **Sonarr** and **Radarr**, enter the address, port, and API key of each application. +2. Under **Languages**, choose your subtitle languages and create a language profile. +3. Under **Providers**, enable the subtitle providers you want to use. + +To reach Sonarr or Radarr in another stack, see the [DNS section of the standard setup](../../documentation/standard-setup.md#dns). + +## Links + +- [Bazarr setup guide](https://wiki.bazarr.media/Getting-Started/Setup-Guide/) +- [Bazarr source code](https://github.com/morpheus65535/bazarr) +- [LinuxServer.io image documentation](https://docs.linuxserver.io/images/docker-bazarr/) diff --git a/services/bentopdf/README.md b/services/bentopdf/README.md index 7db369cb..9e028e52 100644 --- a/services/bentopdf/README.md +++ b/services/bentopdf/README.md @@ -1,33 +1,31 @@ -# BentoPDF with Tailscale Sidecar Configuration +# BentoPDF -This Docker Compose configuration sets up **BentoPDF** with a Tailscale sidecar container, enabling secure access to your self-hosted PDF management interface over your private Tailscale network. With this setup, your BentoPDF instance remains **private and accessible only from authorized devices on your Tailnet**, keeping your documents protected from public exposure. +[BentoPDF](https://github.com/alam00000/bentopdf) is a toolkit for PDF files. You merge, split, compress, convert, and edit PDF files in your browser, and the files do not leave your device. -## BentoPDF +This stack runs BentoPDF with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[**BentoPDF**](https://github.com/alam00000/bentopdf) is an open-source, self-hosted web application for **viewing, organizing, and managing PDF documents**. It provides a clean, modern interface focused on simplicity and performance, making it ideal for personal document libraries, internal teams, or homelab environments that require private document access. +## At a glance -## Key Features +| Item | Value | +| ------------- | ----------------------------------- | +| Web interface | `https://bentopdf..ts.net` | +| Service port | `8080` | +| Image | `ghcr.io/alam00000/bentopdf` | +| Data | None | -- 📄 **In-Browser PDF Viewer** – View PDF files directly from a modern web interface. -- 🗂 **Document Organization** – Browse and manage PDFs stored on your server. -- 🔍 **Fast & Lightweight** – Minimal overhead with a focus on performance. -- 🧭 **Clean, Minimal UI** – Simple and distraction-free user experience. -- 🐳 **Docker-Friendly** – Designed to run easily in containerized environments. -- 🔐 **Privacy-First** – Your documents stay entirely on your own infrastructure. -- 📦 **Open Source** – Fully open-source and self-hostable. +## Before you start -## Why Self-Host? +Nothing beyond the [Quick Start](../../README.md#quick-start). -PDF files often contain sensitive personal or business information. Self-hosting BentoPDF ensures **full control and ownership of your documents**, without relying on third-party cloud storage or services. Combined with Tailscale, BentoPDF becomes a private document portal that is securely accessible from anywhere while remaining invisible to the public internet. +## Deviations from the standard setup -## Configuration Overview +- **No application data.** BentoPDF processes the files in your browser and stores nothing on the server. The `./bentopdf-data/app/config` volume from the template stays empty. +- **Service port.** BentoPDF listens on port `8080`. `SERVICEPORT` in `.env` is only the host port of the optional `ports` block. -In this deployment, a **Tailscale sidecar container** (for example `tailscale-bentopdf`) runs the Tailscale client and joins your private Tailscale network. The main `bentopdf` service uses: +## First run -```plain -network_mode: service:tailscale -``` +Nothing to set up. Open the web interface. -This configuration routes all traffic through the Tailscale interface, ensuring that the BentoPDF web UI is accessible **only via your Tailscale network**. This provides a simple and secure way to access your PDF library from all trusted devices. +## Links -BentoPDF listens on port `8080` inside the container. If you enable the optional host mapping, `SERVICEPORT` is the host port and maps to container port `8080`. +- [BentoPDF documentation and source code](https://github.com/alam00000/bentopdf) diff --git a/services/beszel-agent/README.md b/services/beszel-agent/README.md index 3826dddb..3c533c6b 100644 --- a/services/beszel-agent/README.md +++ b/services/beszel-agent/README.md @@ -1,11 +1,38 @@ -# Beszel Agent with Tailscale Sidecar Configuration +# Beszel Agent -This Docker Compose configuration integrates the [Beszel](https://github.com/henrygd/beszel) Agent with Tailscale in a sidecar setup to enhance secure communication over a private Tailscale network. By utilizing Tailscale, this configuration ensures that the Agent's communication with the Hub remains secure and private within your Tailscale network. Thanks to @[henrygd](https://github.com/henrygd) for the tool development. +[Beszel](https://beszel.dev/) is a lightweight server monitoring platform. The agent collects the statistics of one system and its Docker containers for a [Beszel hub](../beszel-hub/). -## Beszel Agent +This stack runs Beszel Agent with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -The Beszel Agent is the client-side component that connects to the Hub to send and receive messages. Multiple agents can connect to a single Hub, enabling secure communication across different devices. The Agent also benefits from the Tailscale sidecar, ensuring that its communication with the Hub is conducted over a secure, private network. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | ----------------------------------------------------- | +| Web interface | None | +| Agent port | `45876` on the Tailscale IP address of `beszel-agent` | +| Image | `henrygd/beszel-agent` | +| Data | None | -In this setup, the `tailscale` service runs Tailscale, which manages secure networking for the Beszel Agent service. The Agent service connects to the Tailscale network stack using Docker's `network_mode: service:tailscale` configuration. This setup guarantees that the Agent's communication channels are only accessible through the Tailscale network, providing an extra layer of security and privacy. +## Before you start + +The agent only starts with the public key of your hub. + +1. In the web interface of the hub, select **Add System** and copy the public key. +2. In `compose.yaml`, replace the value of `KEY` with that key. + +Without a valid key, the `application` container keeps restarting. + +## Deviations from the standard setup + +- **No web interface.** The stack has no Tailscale Serve configuration and no `./config` folder. The hub connects to the agent on port `45876` of its Tailscale IP address. +- **Docker socket.** The agent mounts `/var/run/docker.sock` read-only to read the statistics of the containers on the Docker host. +- **No data folder.** The agent stores nothing on disk. + +## First run + +In the **Add System** dialog of the hub, enter the Tailscale IP address of the `beszel-agent` device and port `45876`. Your Tailnet policy must allow the hub to reach the agent on that port. + +## Links + +- [Beszel documentation](https://beszel.dev/guide/getting-started) +- [Beszel source code](https://github.com/henrygd/beszel) diff --git a/services/beszel-hub/README.md b/services/beszel-hub/README.md index a209b06f..e45cc58d 100644 --- a/services/beszel-hub/README.md +++ b/services/beszel-hub/README.md @@ -1,11 +1,33 @@ -# Beszel Hub with Tailscale Sidecar Configuration +# Beszel Hub -This Docker Compose configuration integrates the [Beszel](https://github.com/henrygd/beszel) Hub with Tailscale in a sidecar setup to enhance secure communication over a private Tailscale network. By utilizing Tailscale, this configuration ensures that all communication handled by the Hub remains secure and private within your Tailscale network. Thanks to @[henrygd](https://github.com/henrygd) for the tool development. +[Beszel](https://beszel.dev/) is a lightweight server monitoring platform with historical data, Docker statistics, and alerts. The hub is its web interface. It collects the data from an agent on each system that you monitor. -## Beszel Hub +This stack runs Beszel Hub with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -The Beszel Hub is the core component responsible for routing messages between agents and managing the overall communication flow. In this configuration, the Hub runs in its own Docker service and is secured by the Tailscale sidecar, ensuring that all traffic to and from the Hub is encrypted and restricted to your Tailscale network. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | ------------------------------------- | +| Web interface | `https://beszel-hub..ts.net` | +| Service port | `8090` | +| Image | `henrygd/beszel` | +| Data | `./beszel-hub-data/beszel_data` | -In this setup, the `tailscale` service runs Tailscale, which manages secure networking for the Beszel Hub service. The Hub service connects to the Tailscale network stack using Docker's `network_mode: service:tailscale` configuration. This setup guarantees that the Hub's communication channels are only accessible through the Tailscale network, providing an extra layer of security and privacy. +## Before you start + +Nothing beyond the [Quick Start](../../README.md#quick-start). + +## Deviations from the standard setup + +None. + +## First run + +1. Open the web interface and create the first account. +2. Select **Add System**. The dialog shows the public key that an agent needs. +3. Start an agent on each system that you want to monitor, for example with the [Beszel Agent stack](../beszel-agent/), and add it in the same dialog. + +## Links + +- [Beszel documentation](https://beszel.dev/guide/getting-started) +- [Beszel source code](https://github.com/henrygd/beszel) diff --git a/services/booklore/README.md b/services/booklore/README.md index 789f895c..6403a9f9 100644 --- a/services/booklore/README.md +++ b/services/booklore/README.md @@ -1,13 +1,36 @@ -# BookLore with Tailscale Sidecar Configuration +# BookLore -This Docker Compose configuration sets up [BookLore](https://github.com/booklore-app/booklore) with Tailscale as a sidecar container to securely access and manage your book library over a private Tailscale network. By integrating Tailscale, you can ensure that your BookLore instance remains private and accessible only to devices within your Tailscale network. +[BookLore](https://github.com/booklore-app/booklore) manages your book collection and lets you read it in the browser. It supports several users and many book formats, and it synchronises with Kobo and KOReader devices. -## BookLore +This stack runs BookLore with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[BookLore](https://github.com/booklore-app/booklore) is an open-source self-hosted application for managing and reading books. It offers features like multi-user support, Kobo & KOReader sync and support for many formats. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | ---------------------------------------------------- | +| Web interface | `https://booklore..ts.net` | +| Service port | `6060` | +| Images | `ghcr.io/booklore-app/booklore` | +| | `lscr.io/linuxserver/mariadb` | +| Data | `./data` (application data) | +| | `./books` (book library, `/books1` in the container) | +| | `./mariadb_config` (database) | -In this setup, the `tailscale-booklore` service runs Tailscale, which manages secure networking for the BookLore service. The `booklore` service uses the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This ensures that BookLore’s web interface are only accessible through the Tailscale network (or locally, if preferred), providing an extra layer of security and privacy. +## Before you start -BookLore listens on port `6060` inside the container. If you enable the optional host port mapping, `SERVICEPORT` is the host port and maps to container port `6060`. +- **Set the database passwords.** `MYSQL_ROOT_PASSWORD` and `MYSQL_PASSWORD` in `.env` are empty. Give both a random value. +- **Choose your book folder.** To use an existing collection, point the `/books1` volume in `compose.yaml` at your own folder. Otherwise the stack starts with an empty `./books` folder. + +## Deviations from the standard setup + +- **Extra container.** The stack runs a `mariadb` container for the database. It uses the default Compose network, and BookLore reaches it by its service name through Docker's DNS. Keep `TS_ACCEPT_DNS` disabled, because MagicDNS cannot resolve that name. +- **Data folders.** The data is in `./data`, `./books`, and `./mariadb_config`, not in a `./booklore-data` folder. +- **Service port.** BookLore listens on port `6060`. `SERVICEPORT` in `.env` is only the host port of the optional `ports` block. + +## First run + +Open the web interface and create the administrator account. Then create a library with `/books1` as its folder. + +## Links + +- [BookLore documentation and source code](https://github.com/booklore-app/booklore) diff --git a/services/caddy/README.md b/services/caddy/README.md index 32e6c6af..e5ad36b9 100644 --- a/services/caddy/README.md +++ b/services/caddy/README.md @@ -1,24 +1,50 @@ -# Caddy with Tailscale Sidecar Configuration +# Caddy -This Docker Compose configuration sets up [Caddy](https://github.com/caddyserver/caddy-docker) with Tailscale as a sidecar container to securely manage and route your traffic over a private Tailscale network. By integrating Tailscale, you can enhance the security and privacy of your Caddy instance, ensuring that access is restricted to devices within your Tailscale network. +[Caddy](https://caddyserver.com/) is a web server and reverse proxy with automatic HTTPS. In this stack, it serves or proxies your own sites on your Tailnet. -## Caddy +This stack runs Caddy with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Caddy](https://github.com/caddyserver/caddy-docker) is an extensible platform for deploying long-running services ("apps") using a single, unified configuration. It is enterprise-ready, extensible, open source, and provides automatic HTTPS. By incorporating Tailscale, your Caddy instance is safeguarded, ensuring that only authorized users and devices on your Tailscale network can access your applications and services. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | ------------------------------------------------ | +| Web interface | `http://caddy..ts.net` (sample site) | +| Service port | `80` | +| Images | `caddy` | +| | `traefik/whoami` (sample site) | +| Data | `./Caddyfile` (Caddy configuration) | +| | `./site` (static files, `/srv` in the container) | +| | `./caddy_data` (certificates) | +| | `./caddy_config` (saved configuration) | -In this setup, the `tailscale-caddy` service runs Tailscale, which manages secure networking for Caddy. The `application` service uses Docker's `network_mode: service:tailscale` configuration. This keeps Caddy's dashboard and routes on your Tailnet unless you publish a host port. +## Before you start -To get this working: +Replace `caddy.MagicDNSname.ts.net` in `Caddyfile` with the name of the device on your Tailnet, `caddy..ts.net`. If you change `SERVICE` in `.env`, change the name in `Caddyfile` as well. -- Update the FQDN in `Caddyfile` to match your `${SERVICE}.MagicDNSname.ts.net`. -- Update the TS_AUTHKEY in the .env file to your Tailscale key. +## Deviations from the standard setup -If you change `SERVICE` in `.env`, update the hostname in `Caddyfile` as well. The healthcheck calls Caddy's admin API on `127.0.0.1:2019`, so it does not depend on the hostname. +- **No Tailscale Serve.** Caddy answers requests itself, on port `80` of the Tailscale IP address of the device. The stack has no Serve configuration. +- **Sample site.** The stack runs a `whoami` container as a test site, and `Caddyfile` proxies to it. Replace both with your own sites. +- **Tailscale socket.** Both containers mount `./tailscale/tmp`. Caddy uses the Tailscale socket in that folder to request HTTPS certificates. The stack shares the folder and not the socket file, so that Caddy finds the new socket after Tailscale restarts. +- **Data folders.** The data is in `./site`, `./caddy_data`, and `./caddy_config`, not in a `./caddy-data` folder. -Both containers mount the Tailscale socket directory. Caddy only uses the socket to get HTTPS certificates, which the sample `http://` site address does not request (see below). Sharing the directory instead of the socket file lets Caddy use the new socket after Tailscale restarts. +## First run -The example `compose.yaml` uses a simple webserver for testing purposes. +Open `http://caddy..ts.net`. The sample site shows the details of your request. -Within your Tailscale dashboard do you have [HTTPS](https://tailscale.com/kb/1153/enabling-https) and [MagicDNS](https://tailscale.com/kb/1081/magicdns) enabled? If so, remove the http:// from the Caddyfile and Caddy should automatically provision a public HTTPS certificate from Let's Encrypt via the Tailscale infrastructure. The certificate takes ~20s to be procured upon first visit. This is further documented in [Caddy certificates on Tailscale](https://tailscale.com/kb/1190/caddy-certificates). +## Configuration + +### HTTPS + +The sample site uses plain HTTP inside your Tailnet. To use HTTPS: + +1. Enable [MagicDNS](https://tailscale.com/kb/1081/magicdns) and [HTTPS certificates](https://tailscale.com/kb/1153/enabling-https) for your Tailnet. +2. Remove `http://` from the site address in `Caddyfile` and restart the stack. + +Caddy then requests a certificate through Tailscale at the first visit, which takes about 20 seconds. See [Caddy certificates on Tailscale](https://tailscale.com/kb/1190/caddy-certificates). + +## Links + +- [Caddy documentation](https://caddyserver.com/docs/) +- [Caddy Docker image](https://github.com/caddyserver/caddy-docker) +- [Caddy certificates on Tailscale](https://tailscale.com/kb/1190/caddy-certificates) diff --git a/services/changedetection/README.md b/services/changedetection/README.md index c5a692fd..7c2edb43 100644 --- a/services/changedetection/README.md +++ b/services/changedetection/README.md @@ -1,11 +1,31 @@ -# ChangeDetection.io with Tailscale Sidecar Configuration +# changedetection.io -This Docker Compose configuration sets up [ChangeDetection.io](https://github.com/dgtlmoon/changedetection.io) with Tailscale as a sidecar container to securely monitor and access website changes over a private Tailscale network. By using Tailscale in a sidecar configuration, you can ensure that your ChangeDetection.io instance is only accessible within your Tailscale network, providing enhanced security and privacy. +[changedetection.io](https://github.com/dgtlmoon/changedetection.io) watches web pages and notifies you when their content changes, for example for price drops, restocks, or updated documents. -## ChangeDetection.io +This stack runs changedetection.io with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[ChangeDetection.io](https://github.com/dgtlmoon/changedetection.io) is an open-source tool for tracking changes on websites. Whether monitoring prices, content updates, or new product launches, it provides an easy-to-use interface for tracking and alerting you to changes. By integrating Tailscale, you can securely connect to your ChangeDetection.io instance, ensuring that your sensitive tracking information and alerts are protected from unauthorized access. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | ------------------------------------------ | +| Web interface | `https://changedetection..ts.net` | +| Service port | `5000` | +| Image | `ghcr.io/dgtlmoon/changedetection.io` | +| Data | `./changedetection-data/datastore` | -In this setup, the `tailscale-changedetection` service runs Tailscale, which manages secure networking for the ChangeDetection.io service. The `changedetection` service uses the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This setup ensures that ChangeDetection.io’s web interface is only accessible through the Tailscale network (or locally, if preferred), adding an extra layer of security and privacy to your website monitoring setup. +## Before you start + +Nothing beyond the [Quick Start](../../README.md#quick-start). + +## Deviations from the standard setup + +None. + +## First run + +changedetection.io has no password by default. Open the web interface and add the first page to watch. To require a password, set one under **Settings**. + +## Links + +- [changedetection.io documentation](https://github.com/dgtlmoon/changedetection.io/wiki) +- [changedetection.io source code](https://github.com/dgtlmoon/changedetection.io) diff --git a/services/clipcascade/README.md b/services/clipcascade/README.md index 38bf28d8..9f6d89b3 100644 --- a/services/clipcascade/README.md +++ b/services/clipcascade/README.md @@ -1,18 +1,36 @@ -# ClipCascade with Tailscale Sidecar Configuration +# ClipCascade -This Docker Compose configuration sets up [ClipCascade](https://github.com/Sathvik-Rao/ClipCascade) with Tailscale as a sidecar container to securely manage and access your clipboard history over a private Tailscale network. By integrating Tailscale, you can ensure that your ClipCascade instance remains private and accessible only to authorized devices on your Tailscale network. +[ClipCascade](https://github.com/Sathvik-Rao/ClipCascade) synchronises the clipboard between your devices. What you copy on one device is available on the others. -## ClipCascade +This stack runs ClipCascade with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[ClipCascade](https://github.com/Sathvik-Rao/ClipCascade) is a self-hosted, open-source clipboard manager that synchronizes and organizes clipboard history across devices. It offers features like an intuitive web interface, multi-device clipboard synchronization, and searchable history, making it an essential tool for productivity and seamless workflows. By leveraging Tailscale, your ClipCascade instance remains secure and accessible only to devices within your private network. +## At a glance -## Key Features +| Item | Value | +| ------------- | --------------------------------------------- | +| Web interface | `https://clipcascade..ts.net` | +| Service port | `8080` | +| Image | `sathvikrao/clipcascade` | +| Data | `./clipcascade-data/cc_users` (user database) | -- **Multi-Device Sync**: Synchronize clipboard history across multiple devices. -- **Searchable History**: Easily search and retrieve past clipboard entries. -- **Self-Hosted Privacy**: Keep your clipboard data secure and private. -- **User-Friendly Interface**: Manage clipboard history through an intuitive web interface. +## Before you start -## Configuration Overview +Nothing beyond the [Quick Start](../../README.md#quick-start). -In this setup, the `tailscale-clipcascade` service runs Tailscale, which manages secure networking for the ClipCascade service. The `clipcascade` service uses the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This ensures that ClipCascade’s web interface and functionality are only accessible through the Tailscale network (or locally, if preferred), providing enhanced privacy and security for managing your clipboard history. +## Deviations from the standard setup + +None. + +## First run + +Open the web interface and log in with username `admin` and password `admin123`. Change the password right after you log in. + +In the ClipCascade apps, use `https://clipcascade..ts.net` as the server address. The device must be connected to your Tailnet. + +## Configuration + +`CC_MAX_MESSAGE_SIZE_IN_MiB` in `compose.yaml` limits the size of a clipboard item. The stack sets it to `1`. + +## Links + +- [ClipCascade documentation and source code](https://github.com/Sathvik-Rao/ClipCascade) diff --git a/services/coder/README.md b/services/coder/README.md index 3553c46b..bd6684da 100644 --- a/services/coder/README.md +++ b/services/coder/README.md @@ -1,29 +1,45 @@ -# Coder with Tailscale Sidecar Configuration +# Coder -This Docker Compose configuration sets up [**Coder**](https://github.com/coder/coder) with Tailscale as a sidecar container, enabling secure access to your self-hosted cloud development environments from anywhere on your private Tailscale network. With this setup, your Coder instance remains fully private and accessible only from authorized devices. +[Coder](https://coder.com/) provisions development environments on your own infrastructure. You define a workspace as a Terraform template and open it in your browser or your local editor. -## Coder +This stack runs Coder with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[**Coder**](https://github.com/coder/coder) is an open-source, self-hosted platform that allows developers to define, provision, and secure web-based IDE workspaces (e.g., code-server, Jupyter) on cloud or local infrastructure. Environments are managed via Terraform templates, automatically shutdown when idle, and accessible through a browser or local IDE—perfect for teams or individuals seeking reproducible, isolated dev environments without cloud vendor lock-in. +## At a glance -## Key Features +| Item | Value | +| ------------- | ----------------------------------------------- | +| Web interface | `https://coder..ts.net` | +| Service port | `7080` | +| Images | `ghcr.io/coder/coder` | +| | `postgres:17` | +| Data | `./coder-data/coder-home` (Coder home folder) | +| | `./coder-data/coder-data` (PostgreSQL database) | -* **Terraform-Based Environments** – Provision Docker, VM, Kubernetes workspaces via versioned infrastructure. -* **Browser & Local IDE Support** – Use in-browser VS Code or connect via local VS Code / JetBrains. -* **Auto-Scaling & Idle Shutdown** – Automatically stop idle workspaces to optimize resource usage. -* **AI & Agent Integration** – Designed to support AI coding agents and secure development workflows. -* **Self-Hosted & Secure** – Keep full control on your infrastructure, behind your firewall. -* **Private by Default with Tailscale** – Runs behind a Tailscale sidecar for private access only. +## Before you start -## Configuration Overview +1. Create the home folder yourself and make user `1000` its owner. Docker creates missing folders as user `root`. The Coder image runs as user and group `1000` and then fails with `mkdir /home/coder/.cache: permission denied`. -In this deployment, the `tailscale-coder` service runs the Tailscale client to establish a secure private network. The `coder` container uses `network_mode: service:tailscale` to route all traffic through the Tailscale interface. This ensures that your development environments, admin UI, and web IDEs are only accessible via Tailscale, preventing public exposure. + ```bash + mkdir -p coder-data/coder-home + sudo chown 1000:1000 coder-data/coder-home + ``` -## Volume Permissions +2. Set these values in `.env`: -The Coder image runs as UID/GID `1000`. Docker creates missing bind-mount directories as `root:root`, and Coder then fails with `mkdir /home/coder/.cache: permission denied`. Create the home directory before the first start: + - **`CODER_ACCESS_URL`.** The address of the web interface, `https://coder..ts.net`. + - **`POSTGRES_PASSWORD`.** The password of the database. -```sh -mkdir -p coder-data/coder-home -sudo chown 1000:1000 coder-data/coder-home -``` +## Deviations from the standard setup + +- **Extra container.** The stack runs a `database` container with PostgreSQL. It uses the network of the `tailscale` container as well, so Coder reaches it at `localhost`. PostgreSQL therefore also listens on port `5432` of the Tailscale IP address of the device. +- **Docker socket.** Coder mounts `/var/run/docker.sock` read-only, so that templates can use Docker on the host. +- **Image version.** `CODER_VERSION` in `.env` selects the version of the Coder image. + +## First run + +Open the web interface and create the first account, which becomes the administrator. + +## Links + +- [Coder documentation](https://coder.com/docs) +- [Coder source code](https://github.com/coder/coder) diff --git a/services/configarr/README.md b/services/configarr/README.md index f37df56e..16978f09 100644 --- a/services/configarr/README.md +++ b/services/configarr/README.md @@ -1,41 +1,40 @@ -# Configarr with Tailscale Sidecar Configuration +# Configarr -This Docker Compose configuration sets up **Configarr** with a Tailscale sidecar container, enabling secure and private management of configuration files for your *Radarr*, *Sonarr*, and broader media automation stack. With this setup, Configarr is **only accessible from within your Tailscale network**, keeping your configuration workflows fully private and under your control. +[Configarr](https://github.com/raydak-labs/configarr) keeps the settings of Radarr, Sonarr, and related applications in sync with YAML files. It applies custom formats and quality profiles, for example from the TRaSH Guides. -## Configarr +This stack runs Configarr with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[**Configarr**](https://github.com/raydak-labs/configarr) is a configuration management tool designed to **declaratively manage and synchronize settings** for Radarr, Sonarr, and related media services. By defining your desired state in version-controlled YAML files, Configarr ensures your media applications remain consistent, reproducible, and easy to maintain. +## At a glance -## Key Features +| Item | Value | +| ------------- | ---------------------------------------------------------------- | +| Web interface | None | +| Image | `ghcr.io/raydak-labs/configarr` | +| Data | `./configarr-data/config` (your `config.yml` and `secrets.yml`) | +| | `./configarr-data/dockerrepos` (downloaded guides and templates) | -* ⚙️ **Declarative Configuration Management** – Define Radarr and Sonarr settings in YAML. -* 🔁 **Idempotent Syncing** – Apply configurations safely and repeatedly without drift. -* 📦 **Multi-Instance Support** – Manage multiple Radarr/Sonarr instances from a single config. -* 🧩 **Profile & Root Folder Management** – Keep paths, profiles, and settings aligned. -* 🛠 **Automation-Friendly** – Ideal for cron jobs, CI pipelines, or GitOps-style workflows. -* 🧪 **Dry-Run Mode** – Preview configuration changes before applying them. -* 🐳 **Docker-Native** – Lightweight and easy to deploy in containerized environments. +## Before you start -## Why Self-Host? +Create `config.yml` and `secrets.yml` in `./configarr-data/config`. The [Configarr documentation](https://configarr.de/docs/intro) describes both files. To reach Radarr or Sonarr in another stack, see the [DNS section of the standard setup](../../documentation/standard-setup.md#dns). -Configarr requires **API access to Radarr and Sonarr**, exposing configuration and library metadata that should not be publicly reachable. By self-hosting Configarr behind Tailscale, you gain: +## Deviations from the standard setup -* Private, encrypted access to all Radarr/Sonarr APIs -* No need to expose management endpoints to the public Internet -* Secure remote configuration management across locations +- **No web interface.** The stack has no Tailscale Serve configuration and no `./config` folder. Configarr only makes outgoing connections to your applications. +- **Runs once.** The `application` container runs one sync and then exits, so the stack uses `restart: "no"`. -This is especially useful for homelabs, shared servers, and environments where consistent configuration and security are critical. +## First run -## Configuration Overview +Start the stack and read the result of the sync in the log: -In this deployment, a **Tailscale sidecar container** (for example, `tailscale-configarr`) runs the Tailscale client and joins your private Tailscale network. The Configarr service uses: - -```plain -network_mode: service:tailscale +```bash +docker compose up -d +docker logs app-configarr ``` -This setup ensures that **all Configarr network traffic flows exclusively through the Tailscale interface**, allowing it to securely communicate with Radarr and Sonarr instances that are also connected via Tailscale. No ports need to be exposed, and the service remains completely inaccessible from the public Internet. +To sync on a schedule, run `docker compose up application` from cron or another scheduler. -The Configarr container runs one sync and then exits, so the Compose file uses `restart: "no"`. To run it on a schedule, trigger `docker compose up application` from cron or another scheduler. +## Links -With this configuration, Configarr can safely enforce and maintain your desired media configuration state — privately, securely, and reproducibly. +- [Configarr documentation](https://configarr.de/docs/intro) +- [Configarr source code](https://github.com/raydak-labs/configarr) +- [Configarr presets](https://github.com/ChillBill77/configarr-presets) diff --git a/services/convertx/README.md b/services/convertx/README.md index 8d10844d..4a3b2b9e 100644 --- a/services/convertx/README.md +++ b/services/convertx/README.md @@ -1,11 +1,30 @@ -# ConvertX with Tailscale Sidecar Configuration +# ConvertX -This Docker Compose configuration sets up [ConvertX](https://github.com/C4illin/ConvertX) with Tailscale as a sidecar container to securely access your media conversion tool over a private Tailscale network. By using Tailscale in a sidecar configuration, you can enhance the security and privacy of your ConvertX instance, ensuring that it is only accessible within your Tailscale network. +[ConvertX](https://github.com/C4illin/ConvertX) is a file converter that runs in your browser. It converts documents, images, audio, video, and many other formats on your own server. -## ConvertX +This stack runs ConvertX with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[ConvertX](https://github.com/C4illin/ConvertX) is a self-hosted, user-friendly media conversion tool designed to automate the process of converting media files using hardware acceleration where available. It supports batch conversion and integrates smoothly with media server workflows. This setup uses Tailscale to expose your ConvertX instance only to trusted devices within your private Tailscale network, keeping the web interface protected from public access. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | ----------------------------------- | +| Web interface | `https://convertx..ts.net` | +| Service port | `3000` | +| Image | `ghcr.io/c4illin/convertx` | +| Data | `./convertx-data` | -In this setup, the `tailscale-convertx` service runs Tailscale, which manages secure networking for the ConvertX service. The `convertx` service uses the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This ensures that ConvertX’s web interface is only accessible through the Tailscale network (or locally, if preferred), providing an additional layer of security and privacy for your self-hosted media conversion workflow. +## Before you start + +Replace the value of `JWT_SECRET` in `compose.yaml` with your own long random string. The sample value is public, and ConvertX uses it to sign the login tokens. + +## Deviations from the standard setup + +None. + +## First run + +Open the web interface. ConvertX sends you to the setup page, where you create your account. Do this right after the first start, because anyone who can reach the service can register the first account. After that, registration is closed. + +## Links + +- [ConvertX documentation and source code](https://github.com/C4illin/ConvertX) diff --git a/services/copyparty/README.md b/services/copyparty/README.md index 0a6a22b9..f8464711 100644 --- a/services/copyparty/README.md +++ b/services/copyparty/README.md @@ -1,27 +1,34 @@ -# Copyparty with Tailscale Sidecar Configuration +# Copyparty -This Docker Compose configuration sets up [Copyparty](https://github.com/9001/copyparty) with Tailscale as a sidecar container to securely access your lightweight file server and sharing platform over a private Tailscale network. By using Tailscale in a sidecar configuration, you can enhance the security and accessibility of your Copyparty instance, ensuring it is only available within your Tailscale network. +[Copyparty](https://github.com/9001/copyparty) is a file server. You upload, download, and share the files of a folder in your browser, and it also offers protocols such as WebDAV. -## Copyparty +This stack runs Copyparty with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Copyparty](https://github.com/9001/copyparty) is a versatile, self-contained file server that runs on virtually any system. It supports file uploads, downloads, media streaming, WebDAV, and even full-on public or private file sharing with user authentication. Designed to be fast and lightweight, it requires no external dependencies and is extremely customizable. With this setup, Copyparty is exposed only to your Tailscale network, providing secure, peer-to-peer access from your devices. +## At a glance -**Key Features:** +| Item | Value | +| ------------- | -------------------------------------------------------------------- | +| Web interface | `https://copyparty..ts.net` | +| Service port | `3923` | +| Image | `copyparty/ac` | +| Data | The folder that you mount at `/w` (your files) | +| | `./config` (Copyparty configuration folder, `/cfg` in the container) | -- 📤 Drag-and-drop uploads via the browser -- 📁 Directory listing and browsing -- 🔒 User authentication and permissions -- 🌐 WebDAV support for file mounts and syncing -- 🎵 Audio/video streaming with built-in media player -- 📝 Built-in text editor and image previews -- 🧩 Single binary, no dependencies required -- 🖥️ Runs on any OS, including Linux, Windows, macOS, and even Android -- 🔧 Highly configurable with powerful CLI flags and config options +## Before you start -With Tailscale in place, all of these features are securely tunneled through your private mesh network—no need to expose ports to the public internet. +- **Choose the folder to share.** Replace `/path/to/your/fileshare/top/folder` in `compose.yaml` with the absolute path of a folder on the Docker host. User `1000` needs write access to it. +- **Change the password.** The `copyparty-config` block in `compose.yaml` creates the account `admin` with the password `changeme`. Replace the password. -## Configuration Overview +## Deviations from the standard setup -In this setup, the `tailscale-copyparty` service runs Tailscale, which handles the secure networking layer. The `copyparty` service uses Docker’s `network_mode: service:tailscale` setting to share the network stack of the Tailscale container. This means the Copyparty web interface and all file sharing functionality are only accessible via the Tailscale network (or locally if preferred), adding a strong privacy layer to your self-hosted file server. +- **Configuration in `compose.yaml`.** The `copyparty-config` block is the Copyparty configuration file. It defines the account and gives it read and write access to the shared folder. +- **Fixed user.** The `application` container runs as user and group `1000` through the `user` setting. +- **Shared configuration folder.** Copyparty mounts `./config`, the folder that also holds the Tailscale configuration files. -Before starting the stack, replace `/path/to/your/fileshare/top/folder` in `compose.yaml` with an absolute host directory for the files Copyparty should serve. +## First run + +Open the web interface and log in with the password from the `copyparty-config` block. Copyparty then shows the files of your folder. + +## Links + +- [Copyparty documentation and source code](https://github.com/9001/copyparty) diff --git a/services/cyberchef/README.md b/services/cyberchef/README.md index 327279ff..98a58c6d 100644 --- a/services/cyberchef/README.md +++ b/services/cyberchef/README.md @@ -1,11 +1,31 @@ -# CyberChef with Tailscale Sidecar Configuration +# CyberChef -This Docker Compose configuration sets up [CyberChef](https://github.com/gchq/CyberChef) with Tailscale as a sidecar container to securely access your data analysis and manipulation tool over a private Tailscale network. By using Tailscale in a sidecar configuration, you can enhance the security and privacy of your CyberChef instance, ensuring that it is only accessible within your Tailscale network. +[CyberChef](https://github.com/gchq/CyberChef) is a web application for encoding, decoding, encrypting, compressing, and analysing data. You combine operations into a recipe by drag and drop. -## CyberChef +This stack runs CyberChef with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[CyberChef](https://github.com/gchq/CyberChef) is an open-source web application designed to simplify the process of carrying out complex data analysis and encoding/decoding operations. It features a user-friendly drag-and-drop interface that enables users to create "recipes" for analyzing and manipulating data. This configuration leverages Tailscale to securely connect to your CyberChef instance, ensuring that your powerful data tool is protected from unauthorized access and that it is only accessible via your private Tailscale network. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | ------------------------------------ | +| Web interface | `https://cyberchef..ts.net` | +| Service port | `8080` | +| Image | `ghcr.io/gchq/cyberchef` | +| Data | None | -In this setup, the `tailscale-cyberchef` service runs Tailscale, which manages secure networking for the CyberChef service. The `cyberchef` service uses the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This setup ensures that CyberChef’s web interface is only accessible through the Tailscale network (or locally, if preferred), providing an extra layer of security and privacy for your self-hosted data analysis tool. +## Before you start + +Nothing beyond the [Quick Start](../../README.md#quick-start). + +## Deviations from the standard setup + +- **No data folder.** CyberChef runs in your browser and stores nothing on the server, so the stack has no volumes. + +## First run + +Nothing to set up. Open the web interface. + +## Links + +- [CyberChef documentation](https://github.com/gchq/CyberChef/wiki) +- [CyberChef source code](https://github.com/gchq/CyberChef) diff --git a/services/ddns-updater/README.md b/services/ddns-updater/README.md index 999d950b..2327a9a1 100644 --- a/services/ddns-updater/README.md +++ b/services/ddns-updater/README.md @@ -1,27 +1,37 @@ -# DDNS Updater with Tailscale Sidecar Configuration +# DDNS Updater -This Docker Compose configuration sets up [DDNS Updater](https://github.com/qdm12/ddns-updater) with Tailscale as a sidecar container, enabling secure and private management of your dynamic DNS records over a Tailscale network. Integrating Tailscale ensures that your DDNS Updater instance is accessible only to authorized devices within your Tailnet, enhancing the security of your DNS management. +[DDNS Updater](https://github.com/qdm12/ddns-updater) keeps the DNS records of your domains pointed at your current public IP address. It supports many DNS providers and shows the state of each record in a web interface. -## DDNS Updater +This stack runs DDNS Updater with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[DDNS Updater](https://github.com/qdm12/ddns-updater) is a lightweight, universal program designed to keep your DNS A and/or AAAA records updated across multiple DNS providers. It supports a wide range of DNS services, including Cloudflare, DuckDNS, and many others. Key features include: +## At a glance -- **Periodic Updates**: Automatically updates DNS records at specified intervals to ensure they always point to your current IP address. -- **Web User Interface**: Provides a user-friendly web UI for monitoring and managing your DNS records. -- **Multi-Provider Support**: Compatible with numerous DNS providers, offering flexibility in your DNS management. -- **Docker Compatibility**: Available as a lightweight Docker image, facilitating easy deployment and integration into existing setups. +| Item | Value | +| ------------- | ---------------------------------------------------------------------- | +| Web interface | `https://ddns-updater..ts.net` | +| Service port | `8000` | +| Image | `qmcgaw/ddns-updater` | +| Data | `./ddns-updater-data/data` (your `config.json` and the update history) | -By combining DDNS Updater with Tailscale, you can securely manage your dynamic DNS records without exposing the service to the public internet. +## Before you start -## Configuration Overview +Create the data folder yourself and make user `1000` its owner. Docker creates missing folders as user `root`. DDNS Updater runs as user `1000` and then exits with `permission denied` when it writes `config.json`. -In this setup, the `tailscale-ddns-updater` service runs Tailscale, providing a secure networking layer for the DDNS Updater service. The `ddns-updater` service utilizes Docker's `network_mode: service:tailscale` configuration to route all traffic through the Tailscale network. This setup ensures that the DDNS Updater's web interface and API are only accessible within your private Tailnet, adding an extra layer of security to your DNS management. - -## Volume Permissions - -The DDNS Updater image runs as UID `1000`. Docker creates missing bind-mount directories as `root:root`, and DDNS Updater then exits with `permission denied` when it writes `config.json`. Create the data directory before the first start: - -```sh +```bash mkdir -p ddns-updater-data/data sudo chown -R 1000:1000 ddns-updater-data ``` + +## Deviations from the standard setup + +- **Settings through environment variables.** `compose.yaml` sets the update period, the services that report your public IP address, and the port of the web interface. + +## First run + +1. Start the stack once. DDNS Updater creates an empty `config.json` in `./ddns-updater-data/data`. +2. Add your domains and DNS providers to that file. The [DDNS Updater documentation](https://github.com/qdm12/ddns-updater#configuration) describes the format for each provider. +3. Restart the stack. The web interface has no login and shows the state of each record. + +## Links + +- [DDNS Updater documentation and source code](https://github.com/qdm12/ddns-updater) diff --git a/services/dockge/README.md b/services/dockge/README.md index 54fccc67..365be179 100644 --- a/services/dockge/README.md +++ b/services/dockge/README.md @@ -1,23 +1,33 @@ -# Dockge with Tailscale Sidecar Configuration +# Dockge -This Docker Compose configuration sets up Dockge with a Tailscale sidecar container, enabling secure, private access to your Docker Compose management UI over your Tailnet. With this setup, your Dockge instance is not exposed to the public internet and is only accessible from authorized devices connected via Tailscale. +[Dockge](https://github.com/louislam/dockge) is a web interface to manage Docker Compose stacks. You create, edit, start, and update your `compose.yaml` files in the browser. -## Dockge +This stack runs Dockge with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Dockge](https://github.com/louislam/dockge) is a lightweight, self-hosted Docker Compose stack manager built for simplicity and control. Created by the developer behind Uptime Kuma, Dockge provides an intuitive web interface for managing, editing, and deploying docker-compose.yml stacks without relying solely on the CLI. +## At a glance -It is especially well-suited for homelabs, self-hosted environments, and DevOps workflows where multiple services are managed via Docker Compose. +| Item | Value | +| ------------- | -------------------------------------------------- | +| Web interface | `https://dockge..ts.net` | +| Service port | `5001` | +| Image | `louislam/dockge:1` | +| Data | `./dockge-data/app/config` (Dockge settings) | +| | The folder from `STACKS_DIR` (your Compose stacks) | -## Key Features +## Before you start -* 🐳 Web-based Docker Compose stack management -* ✏️ Live editing of docker-compose.yml files -* ▶️ One-click start, stop, and restart of stacks -* 📜 Real-time container logs viewer -* 📦 Multi-stack organization via directories -* ⚡ Lightweight and fast interface -* 🔍 Clear visibility into container status +Set `STACKS_DIR` in `.env` to the absolute path of the folder on the Docker host that holds your stacks. The stack mounts it at the same path in the container. The default is `/opt/stacks`. -## Important Notice +## Deviations from the standard setup -Set `STACKS_DIR` in `.env` to an absolute host path. The Compose file mounts that path at the same path inside the container. The sample uses `/opt/stacks`. +- **Docker socket.** Dockge mounts `/var/run/docker.sock` with write access, which it needs to manage your stacks. Everyone who can log in to Dockge has full control over the Docker host. +- **Stacks folder.** The stacks are in the folder from `STACKS_DIR`, outside this directory. +- **User and group.** `PUID` and `PGID` in `.env` set the owner of the stack files. + +## First run + +Open the web interface and create the administrator account. + +## Links + +- [Dockge documentation and source code](https://github.com/louislam/dockge) diff --git a/services/dockhand/README.md b/services/dockhand/README.md index a6c63d94..5c0422de 100644 --- a/services/dockhand/README.md +++ b/services/dockhand/README.md @@ -1,38 +1,30 @@ -# Dockhand with Tailscale Sidecar Configuration +# Dockhand -This Docker Compose configuration sets up **Dockhand** with a Tailscale sidecar container, enabling secure access to your self-hosted Docker management interface over your private Tailscale network. With this setup, your Dockhand instance remains private and accessible only from authorized devices on your Tailnet, ensuring that container management and infrastructure controls are never exposed to the public internet. +[Dockhand](https://github.com/Finsys/dockhand) is a web interface to manage Docker. You manage containers, images, volumes, networks, and Compose stacks on local and remote Docker hosts. -## Dockhand +This stack runs Dockhand with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[**Dockhand**](https://github.com/Finsys/dockhand) is a modern, lightweight Docker management UI focused on real-time container operations and multi-environment orchestration. It provides an intuitive interface for managing containers, images, volumes, networks, and Docker Compose stacks across local or remote Docker hosts. +## At a glance -Dockhand is designed for operators and homelab environments that want a clean, responsive alternative to heavier container management platforms, while still retaining full control over their infrastructure. +| Item | Value | +| ------------- | ----------------------------------- | +| Web interface | `https://dockhand..ts.net` | +| Service port | `3000` | +| Image | `fnsys/dockhand` | +| Data | `./dockhand-data` | -## Key Features +## Before you start -- Container Management – Start, stop, restart, and inspect containers in real time. -- Compose Stack Support – Deploy and manage Docker Compose applications. -- Multi-Environment Support – Connect to and manage multiple Docker hosts. -- Live Logs & Terminal – Stream logs and access container terminals directly from the UI. -- File & Volume Access – Inspect volumes and container file systems. -- Git-Based Deployments – Deploy stacks from Git repositories with optional sync. -- Docker-Native – Built specifically for Docker environments. -- Open Source – Community-driven and self-hostable. +Nothing beyond the [Quick Start](../../README.md#quick-start). -## Why Self-Host? +## Deviations from the standard setup -A Docker management interface has full control over your infrastructure. Exposing such a tool publicly significantly increases risk, as it can allow attackers to manipulate containers, access secrets, or pivot deeper into your network. +- **Docker socket.** Dockhand mounts `/var/run/docker.sock` with write access, which it needs to manage Docker. Everyone who can reach Dockhand has full control over the Docker host. -Self-hosting Dockhand ensures that you maintain full ownership and operational control. When combined with Tailscale, Dockhand becomes a secure, private control plane for your Docker environments, accessible only from authenticated devices within your Tailnet. This dramatically reduces the attack surface while preserving remote management convenience. +## First run -## Configuration Overview +Open the web interface. Dockhand has no login by default, so everyone who can reach the device on your Tailnet can manage Docker. Enable authentication in the settings. -In this deployment, a Tailscale sidecar container (for example `tailscale-dockhand`) runs the Tailscale client and joins your private Tailscale network. The main `dockhand` service uses: +## Links -```plain -network_mode: service:tailscale -``` - -This configuration routes all inbound and outbound traffic through the Tailscale interface, ensuring that the Dockhand web interface and Docker API interactions are accessible only via your Tailscale network. - -By avoiding public port mappings and relying exclusively on Tailnet access, you create a secure-by-default Docker management setup suitable for homelabs, remote infrastructure, and internal DevOps environments. +- [Dockhand documentation and source code](https://github.com/Finsys/dockhand) diff --git a/services/docmost/README.md b/services/docmost/README.md index 09f4c372..8b3be56a 100644 --- a/services/docmost/README.md +++ b/services/docmost/README.md @@ -1,33 +1,43 @@ -# Docmost with Tailscale Sidecar Configuration +# Docmost -This Docker Compose configuration sets up [**Docmost**](https://github.com/docmost/docmost) with Tailscale as a sidecar container, enabling secure access to your collaborative wiki and documentation platform from anywhere on your private Tailscale network. With this setup, your Docmost instance remains fully private and accessible only to authorized users. +[Docmost](https://docmost.com/) is a wiki and documentation tool for teams. Several people edit a page at the same time, and it supports diagrams, comments, page history, and permissions. -## Docmost +This stack runs Docmost with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[**Docmost**](https://github.com/docmost/docmost) is an open-source, self-hosted wiki and documentation tool designed for teams that want real-time collaboration without vendor lock-in. It offers a sleek interface with support for rich editing, diagrams, permissions, inline comments, page history, and file attachments. +## At a glance -## Key Features +| Item | Value | +| ------------- | ---------------------------------------------- | +| Web interface | `https://docmost..ts.net` | +| Service port | `3000` | +| Images | `docmost/docmost` | +| | `postgres:16-alpine` | +| | `redis:7.2-alpine` | +| Data | `./docmost-data/docmost` (uploaded files) | +| | `./docmost-data/db-data` (PostgreSQL database) | +| | `./docmost-data/redis-data` (Redis data) | -* **Real-Time Collaboration** – Multiple users can edit simultaneously with live syncing. -* **Diagrams & Math** – Support for Mermaid, Draw\.io, Excalidraw, and LaTeX. -* **Structured Content** – Organize documentation in spaces, nested pages, and groups. -* **Permissions & Comments** – Enforce role-based access while enabling inline discussion. -* **Page History & Export** – View history, revert changes, and import/export Markdown/HTML. -* **Full-Text Search** – Quickly locate documentation across all content. -* **File Attachments** – Embed images, PDFs, and other files. -* **Privacy-first & Self-Hosted** – Keep all data under your control behind Tailscale. +## Before you start -## Configuration Overview +Set these values in `.env`. Compose stops with an error if one of them is empty. -In this configuration, the `tailscale-docmost` service runs the Tailscale client to secure network traffic. The `docmost` service uses `network_mode: service:tailscale`, ensuring all requests are routed through the Tailscale interface. This safeguards your documentation from public exposure, making it accessible only within your private mesh. +- **`APP_SECRET`.** A random value of at least 32 characters. Generate one with `openssl rand -hex 32`. +- **`DB_PASSWORD`.** The password of the database. Use letters and digits only, because the value is part of the database address. PostgreSQL applies it only when it first creates the database. -## Files to check +## Deviations from the standard setup -Please check the following contents for validity as some variables need to be defined upfront. +- **Extra containers.** The stack runs `db` (PostgreSQL) and `redis`. Both use the network of the `tailscale` container as well, so Docmost reaches them at `localhost`. PostgreSQL and Redis therefore also listen on ports `5432` and `6379` of the Tailscale IP address of the device. +- **Application address.** `APP_URL` in `compose.yaml` is `http://localhost:3000`. Docmost uses this value for the links that it generates, for example in emails. Change it to `https://docmost..ts.net` if you use such links. -* `.env` - * Required: `TS_AUTHKEY` - * Required: `APP_SECRET`, at least 32 characters. Generate it with `openssl rand -hex 32`. - * Required: `DB_PASSWORD`. Use letters and digits only, because the value is part of `DATABASE_URL`. +## First run -Compose stops with an error if `APP_SECRET` or `DB_PASSWORD` is empty. PostgreSQL applies `DB_PASSWORD` only when it first creates the database. If you are upgrading, set `APP_SECRET` and `DB_PASSWORD` in `.env` to the values that your `compose.yaml` used before. +Open the web interface. Docmost shows its setup page, where you create your workspace and your account. + +## Upgrading + +If your `compose.yaml` contained the secret and the database password before, set `APP_SECRET` and `DB_PASSWORD` in `.env` to those same values. + +## Links + +- [Docmost documentation](https://docmost.com/docs/) +- [Docmost source code](https://github.com/docmost/docmost) diff --git a/services/donetick/README.md b/services/donetick/README.md index 94fb01b5..e1a8be6b 100644 --- a/services/donetick/README.md +++ b/services/donetick/README.md @@ -1,26 +1,32 @@ -# Donetick with Tailscale Sidecar Configuration +# Donetick -This Docker Compose configuration sets up **[Donetick](https://github.com/donetick/donetick)** with Tailscale as a sidecar container to securely manage and access your self-hosted task management system over a private Tailscale network. By integrating Tailscale, you can ensure that your Donetick instance remains private and accessible only to authorized devices within your Tailscale network. +[Donetick](https://github.com/donetick/donetick) is a task and chore manager for households and small groups. You create tasks, assign them, set a schedule, and track who did what. -## Donetick +This stack runs Donetick with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Donetick](https://github.com/donetick/donetick) is a **self-hosted task and checklist manager** designed for simplicity and efficiency. It helps users stay organized with structured to-do lists and task tracking while ensuring full control over their data. With Donetick, you can create tasks, set deadlines, and track progress without relying on third-party services. By integrating Tailscale, you can further secure your Donetick instance by restricting access to only authorized devices within your private network. +## At a glance -## Key Features +| Item | Value | +| ------------- | ----------------------------------------------------------- | +| Web interface | `https://donetick..ts.net` | +| Service port | `2021` | +| Image | `donetick/donetick` | +| Data | `./donetick-data/config` (configuration, `selfhosted.yaml`) | +| | `./donetick-data/data` (database) | -- **Task & Checklist Management** – Organize and track tasks efficiently. -- **Collaborative Workflows** – Share tasks and checklists with team members. -- **Self-Hosted Privacy** – Keep full control over your task management data. -- **Minimalist & Lightweight** – A simple, distraction-free interface for productivity. -- **Secure Access with Tailscale** – Restrict access to only authorized devices within your private network. +## Before you start -## Configuration Overview +Replace the value of `jwt.secret` in `donetick-data/config/selfhosted.yaml` with your own random value, for example from `openssl rand -base64 32`. Donetick refuses to start with the sample value and reports `JWT secret is too weak`. -In this setup, the `tailscale-donetick` service runs Tailscale, which manages secure networking for the Donetick service. The `donetick` service uses the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This ensures that Donetick’s web interface is only accessible through the Tailscale network (or locally, if preferred), adding an extra layer of security and privacy for managing tasks and checklists. +## Deviations from the standard setup -## Files to check +- **Configuration file.** This directory contains `donetick-data/config/selfhosted.yaml`. `DT_ENV=selfhosted` makes Donetick read that file. -Please check the following contents for validity as some variables need to be defined upfront. +## First run -- `.env` // Main variable `TS_AUTHKEY` -- `donetick-data/config/selfhosted.yaml` // Generate jwt secret with e.g. openssl rand -base64 32 +Open the web interface and sign up to create the first account. + +## Links + +- [Donetick documentation](https://docs.donetick.com/) +- [Donetick source code](https://github.com/donetick/donetick) diff --git a/services/dozzle/README.md b/services/dozzle/README.md index b1034951..f9c8697a 100644 --- a/services/dozzle/README.md +++ b/services/dozzle/README.md @@ -1,11 +1,37 @@ -# Dozzle with Tailscale Sidecar Configuration +# Dozzle -This Docker Compose configuration sets up [Dozzle](https://github.com/amir20/dozzle) with Tailscale as a sidecar container to securely access your real-time Docker log viewer over a private Tailscale network. By using Tailscale in a sidecar configuration, you can enhance the security and privacy of your Dozzle instance, ensuring that it is only accessible within your Tailscale network. +[Dozzle](https://dozzle.dev/) is a web interface to follow the logs of your Docker containers in real time. -## Dozzle +This stack runs Dozzle with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Dozzle](https://github.com/amir20/dozzle) is a lightweight, self-hosted application for viewing Docker container logs in real time. It offers an intuitive web interface that makes it easy to monitor logs from your Docker environment without the need for complex setups or additional dependencies. This configuration leverages Tailscale to securely connect to your Dozzle instance, ensuring that your log viewer is protected from unauthorized access and that your instance is only accessible via your private Tailscale network. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | --------------------------------- | +| Web interface | `https://dozzle..ts.net` | +| Service port | `8080` | +| Image | `amir20/dozzle` | +| Data | `./dozzle-data/dozzle-data` | -In this setup, the `tailscale-dozzle` service runs Tailscale, which manages secure networking for the Dozzle service. The `dozzle` service uses the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This setup ensures that Dozzle’s web interface is only accessible through the Tailscale network (or locally, if preferred), providing an extra layer of security and privacy for your self-hosted log viewer. +## Before you start + +Nothing beyond the [Quick Start](../../README.md#quick-start). + +## Deviations from the standard setup + +- **Docker socket.** Dozzle mounts `/var/run/docker.sock` read-only to read the logs of all containers on the Docker host. + +## First run + +Dozzle has no login by default. Open the web interface to see the containers of the Docker host. Everyone who can reach the device on your Tailnet can read these logs. + +## Configuration + +### Require a login + +Dozzle can ask for a username and password. See [Dozzle authentication](https://dozzle.dev/guide/authentication) for the `simple` provider and its `users.yml` file. The file `dozzle-data/users.yml` in this directory is an example of that format. + +## Links + +- [Dozzle documentation](https://dozzle.dev/guide/getting-started) +- [Dozzle source code](https://github.com/amir20/dozzle) diff --git a/services/dumbdo/README.md b/services/dumbdo/README.md index 2cfc595f..db87f4c8 100644 --- a/services/dumbdo/README.md +++ b/services/dumbdo/README.md @@ -1,18 +1,30 @@ -# DumbDo with Tailscale Sidecar Configuration +# DumbDo -This Docker Compose configuration sets up [DumbDo](https://github.com/DumbWareio/DumbDo) with Tailscale as a sidecar container to securely manage and access your lightweight task manager over a private Tailscale network. By integrating Tailscale, you can ensure that your DumbDo instance remains private and accessible only to authorized devices within your Tailscale network. +[DumbDo](https://github.com/DumbWareio/DumbDo) is a simple to-do list. It has no accounts and no database, and it stores your lists in one file. -## DumbDo +This stack runs DumbDo with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[DumbDo](https://github.com/DumbWareio/DumbDo) is a self-hosted, minimalistic task management tool designed to provide a distraction-free experience for managing to-do lists and tasks. With its simple interface and lightweight nature, DumbDo allows users to focus on productivity without unnecessary complexity. By integrating Tailscale, you can keep your task manager secure and accessible only within your private network. +## At a glance -## Key Features +| Item | Value | +| ------------- | --------------------------------- | +| Web interface | `https://dumbdo..ts.net` | +| Service port | `3000` | +| Image | `dumbwareio/dumbdo` | +| Data | `./dumbdo-data` | -- **Minimalist Task Management** – A straightforward approach to to-do lists without unnecessary complexity. -- **Self-Hosted** – Maintain full control over your data with a locally hosted instance. -- **Lightweight & Fast** – Designed for speed and efficiency without bloated features. -- **Secure Integration** – Pair with Tailscale to restrict access to authorized devices only. +## Before you start -## Configuration Overview +Nothing beyond the [Quick Start](../../README.md#quick-start). -In this setup, the `tailscale-dumbdo` service runs Tailscale, which manages secure networking for the DumbDo service. The `dumbdo` service uses the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This ensures that DumbDo’s web interface is only accessible through the Tailscale network (or locally, if preferred), providing enhanced privacy and security for your task management system. +## Deviations from the standard setup + +None. + +## First run + +Nothing to set up. Open the web interface. DumbDo has no login by default, so everyone who can reach the device on your Tailnet can edit the lists. + +## Links + +- [DumbDo documentation and source code](https://github.com/DumbWareio/DumbDo) diff --git a/services/eigenfocus/README.md b/services/eigenfocus/README.md index 60ebbbc5..bc7d7d08 100644 --- a/services/eigenfocus/README.md +++ b/services/eigenfocus/README.md @@ -1,19 +1,31 @@ -# Eigenfocus with Tailscale Sidecar Configuration +# Eigenfocus -This Docker Compose configuration sets up **[Eigenfocus](https://github.com/Eigenfocus/eigenfocus)** with Tailscale as a sidecar container to securely manage and access your self-hosted task and project management tool over a private Tailscale network. By integrating Tailscale, you can ensure that your Eigenfocus instance remains private and accessible only to authorized devices within your Tailscale network. +[Eigenfocus](https://eigenfocus.com/) is a project and task manager with boards, time tracking, and focus tools. -## Eigenfocus +This stack runs Eigenfocus with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Eigenfocus](https://github.com/Eigenfocus/eigenfocus) is a self-hosted, privacy-focused task and project management tool that helps individuals and teams stay organized. With its clean, minimalist interface and structured workflow, Eigenfocus is designed for those who prefer a lightweight yet powerful alternative to traditional project management apps. By integrating Tailscale, your Eigenfocus instance is secured, allowing access only from trusted devices within your private network. +## At a glance -## Key Features +| Item | Value | +| ------------- | ------------------------------------------------- | +| Web interface | `https://eigenfocus..ts.net` | +| Service port | `3000` | +| Image | `eigenfocus/eigenfocus:0.8.0` | +| Data | `./eigenfocus-data` (database and uploaded files) | -- **Task & Project Management** – Organize tasks, set deadlines, and track progress effortlessly. -- **Privacy-Focused** – Self-hosted to keep your data secure and under your control. -- **Minimalist Interface** – A distraction-free, efficient workflow for productivity. -- **Collaboration Ready** – Share tasks and projects with team members. -- **Secure Access with Tailscale** – Restrict access to only authorized devices within your private network. +## Before you start -## Configuration Overview +Nothing beyond the [Quick Start](../../README.md#quick-start). -In this setup, the `tailscale-eigenfocus` service runs Tailscale, which manages secure networking for the Eigenfocus service. The `eigenfocus` service uses the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This ensures that Eigenfocus’ web interface is only accessible through the Tailscale network (or locally, if preferred), adding an extra layer of security and privacy for managing tasks and projects. +## Deviations from the standard setup + +- **Pinned version.** `IMAGE_URL` in `.env` pins Eigenfocus to version `0.8.0`. + +## First run + +Open the web interface. Eigenfocus sends you to the profile page, where you enter your name and preferences before you create the first project. + +## Links + +- [Eigenfocus website](https://eigenfocus.com/) +- [Eigenfocus source code](https://github.com/Eigenfocus/eigenfocus) diff --git a/services/espocrm/README.md b/services/espocrm/README.md index 1c742f1c..42e782c7 100644 --- a/services/espocrm/README.md +++ b/services/espocrm/README.md @@ -1,30 +1,48 @@ -# EspoCRM with Tailscale Sidecar Configuration +# EspoCRM -This Docker Compose configuration sets up [EspoCRM](https://www.espocrm.com/) with Tailscale as a sidecar container to keep the app reachable over your Tailnet. +[EspoCRM](https://www.espocrm.com/) is a customer relationship management application. You manage your contacts, companies, opportunities, and projects in one web interface. -## EspoCRM +This stack runs EspoCRM with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[EspoCRM](https://www.espocrm.com/) is a web application that allows users to see, enter and evaluate all your company relationships regardless of the type. People, companies, projects or opportunities — all in an easy and intuitive interface. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | --------------------------------------------------------------------------- | +| Web interface | `https://espocrm..ts.net` | +| Service port | `80` | +| Images | `espocrm/espocrm` | +| | `mariadb:12.2` | +| Data | `./espocrm-data/data` (application data) | +| | `./espocrm-data/custom` and `./espocrm-data/client/custom` (customisations) | +| | `./espocrm-db` (MariaDB database) | -In this setup, the `tailscale-EspoCRM` service runs Tailscale, which manages secure networking for EspoCRM. The `EspoCRM` service utilizes the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This keeps the app Tailnet-only unless you intentionally expose ports. +## Before you start -## What to document for users +Set these values in `.env`: -- Links: [EspoCRM Features](https://www.espocrm.com/features/) [Environment Details](https://docs.espocrm.com/administration/docker/installation/#installation-environments) +- **`TS_DOMAIN`.** Your Tailnet name with `.ts.net`. The stack builds the address of the site, `ESPOCRM_SITE_URL`, from `SERVICE` and this value. +- **`ESPOCRM_ADMIN_USERNAME` and `ESPOCRM_ADMIN_PASSWORD`.** The administrator account that EspoCRM creates at the first start. The defaults are `admin` and `password`. +- **`MARIADB_ROOT_PASSWORD`, `MARIADB_PASSWORD`, and `ESPOCRM_DATABASE_PASSWORD`.** The passwords of the database. The default is `password`. `MARIADB_PASSWORD` and `ESPOCRM_DATABASE_PASSWORD` must be the same. -## Files to check +## Deviations from the standard setup -Please check the following contents for validity as some variables need to be defined upfront. +- **Extra container.** The stack runs a `database` container with MariaDB, named `db-espocrm`. It uses the default Compose network, and EspoCRM reaches it by its service name through Docker's DNS. Keep `TS_ACCEPT_DNS` disabled, because MagicDNS cannot resolve that name. +- **Data folders.** The database is in `./espocrm-db`, outside the `./espocrm-data` folder. -- `.env` // Main variable `TS_AUTHKEY` -- `.env` // Required for normal operation. `TS_DOMAIN` +## First run -## Upgrading from an older ScaleTail configuration +Open the web interface and log in with the administrator account from `.env`. -From EspoCRM 10, the upstream Docker setup no longer mounts the whole `/var/www/html` directory. This configuration follows it and mounts only `data`, `custom`, and `client/custom` from `./espocrm-data`, so existing data and customizations stay in place. +## Upgrading + +From EspoCRM 10, the upstream Docker setup no longer mounts the whole `/var/www/html` folder. This stack follows it and mounts only `data`, `custom`, and `client/custom` from `./espocrm-data`, so existing data and customisations stay in place. 1. Back up `./espocrm-data`. 2. Run `docker compose down`, then `docker compose pull` and `docker compose up -d`. 3. Optionally, remove the files that older images copied into `./espocrm-data`, such as `application`, `vendor`, and `bootstrap.php`. The [EspoCRM 10 migration guide](https://docs.espocrm.com/administration/docker/installation/#migration-to-espocrm-10) lists them all. + +## Links + +- [EspoCRM documentation](https://docs.espocrm.com/) +- [EspoCRM Docker installation](https://docs.espocrm.com/administration/docker/installation/) +- [EspoCRM source code](https://github.com/espocrm/espocrm) diff --git a/services/excalidraw/README.md b/services/excalidraw/README.md index 69063be9..7d39cfa5 100644 --- a/services/excalidraw/README.md +++ b/services/excalidraw/README.md @@ -1,11 +1,31 @@ -# Excalidraw with Tailscale Sidecar Configuration +# Excalidraw -This Docker Compose configuration sets up [Excalidraw](https://github.com/excalidraw/excalidraw) with Tailscale as a sidecar container to securely collaborate on whiteboard diagrams over a private Tailscale network. By integrating Tailscale in a sidecar configuration, you can enhance the security and accessibility of your Excalidraw server, ensuring that it is only available within your Tailscale network. +[Excalidraw](https://github.com/excalidraw/excalidraw) is a virtual whiteboard for diagrams and sketches with a hand-drawn look. -## Excalidraw +This stack runs Excalidraw with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Excalidraw](https://github.com/excalidraw/excalidraw) is an open-source virtual whiteboard tool designed for real-time collaboration. It allows users to create diagrams, sketches, and wireframes in a minimalist, hand-drawn style. Excalidraw is easy to set up and supports self-hosting for private, secure collaboration. This configuration incorporates Tailscale to provide a secure connection to your Excalidraw server, protecting your sessions from unauthorized access and enabling private collaboration. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | ------------------------------------- | +| Web interface | `https://excalidraw..ts.net` | +| Service port | `80` | +| Image | `excalidraw/excalidraw` | +| Data | None | -In this setup, the `tailscale-excalidraw` service runs Tailscale, which manages secure networking for the Excalidraw service. The `excalidraw` service utilizes the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This design ensures that Excalidraw's collaboration and editing features are only accessible through the Tailscale network (or locally, if preferred), providing enhanced security and privacy for your self-hosted Excalidraw instance. +## Before you start + +Nothing beyond the [Quick Start](../../README.md#quick-start). + +## Deviations from the standard setup + +- **No application data.** Excalidraw keeps your drawings in the browser and stores nothing on the server. The `./excalidraw-data/app/config` volume from the template stays empty. + +## First run + +Nothing to set up. Open the web interface. + +## Links + +- [Excalidraw documentation](https://docs.excalidraw.com/) +- [Excalidraw source code](https://github.com/excalidraw/excalidraw) diff --git a/services/filebrowser/README.md b/services/filebrowser/README.md index d94ef06c..1ef8335f 100644 --- a/services/filebrowser/README.md +++ b/services/filebrowser/README.md @@ -1,41 +1,44 @@ -# Filebrowser with Tailscale Sidecar Configuration +# File Browser -This Docker Compose configuration sets up **Filebrowser** with a Tailscale sidecar container, enabling secure, private access to your self-hosted web file manager over your Tailnet. With this setup, your Filebrowser instance is **not exposed to the public internet** and is only accessible from authorized devices connected via Tailscale. +[File Browser](https://filebrowser.org/) is a file manager for the browser. You upload, download, preview, rename, edit, and share the files of one folder on your server. -## Filebrowser +This stack runs File Browser with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[**Filebrowser**](https://github.com/filebrowser/filebrowser) is a lightweight, self-hosted web file manager that provides a clean browser-based interface for managing files inside a specified directory. It can be used to upload, download, delete, preview, rename, and edit files directly from a web interface. +## At a glance -Filebrowser is often used as a simple "create-your-own-cloud" style service. You point it at a directory on your server, then manage that directory through the browser instead of needing direct SSH, SMB, SFTP, or local filesystem access. It also supports multiple users, making it useful for small teams, home labs, shared storage locations, and private file management workflows. +| Item | Value | +| ------------- | ---------------------------------------------------------- | +| Web interface | `https://filebrowser..ts.net` | +| Service port | `80` | +| Image | `filebrowser/filebrowser:s6` | +| Data | `./filebrowser-data` (your files, `/srv` in the container) | +| | `./filebrowser-database` (users and settings) | +| | `./filebrowser-config` (configuration) | -## Key Features +## Before you start -- 📂 Web-based file management for a configured server directory -- ⬆️ Upload, download, rename, move, copy, delete, preview, and edit files -- 👥 Multi-user support with user-specific scopes and permissions -- 🔗 File and folder sharing options for controlled access -- 🧭 Simple browser interface for managing server-side files -- 🧰 Lightweight deployment with minimal service overhead -- 🔐 Tailnet-only access when paired with the included Tailscale sidecar +To manage an existing folder, point the `/srv` volume in `compose.yaml` at it. File Browser can change and delete everything in that folder. -## Usage Notes +## Deviations from the standard setup -Make sure to get your initial admin password from the Docker logs. +- **Data folders.** The data is in `./filebrowser-data`, `./filebrowser-database`, and `./filebrowser-config`, next to each other in this directory. -![Initial Admin Password in Logs](images/initial-admin-password-in-logs.png) +## First run -Once logged in, review the configured user accounts, permissions, sharing settings, and file root path before using the service with important data. Since Filebrowser can directly modify files on the mounted host directory, permissions should be treated carefully. +1. File Browser creates the user `admin` with a random password at the first start. Find it in the log: -## Files to Check + ```bash + docker logs app-filebrowser 2>&1 | grep "randomly generated password" + ``` -- `compose.yaml` - Main Docker Compose configuration for Filebrowser and the Tailscale sidecar -- `.env` - Environment variables such as `TS_AUTHKEY`, Tailscale hostname, and any deployment-specific values -- Mounted file directory - Host path exposed to Filebrowser for web-based file management -- Filebrowser database/config path - Persistent storage for users, settings, permissions, and configuration +2. Open the web interface and log in. +3. Change the password, and review the users, permissions, and sharing settings before you use File Browser with important data. -## References +The log line with the password looks like this: -- [Filebrowser Website](https://filebrowser.org/) -- [Filebrowser GitHub Repository](https://github.com/filebrowser/filebrowser) -- [Filebrowser Docker Image](https://hub.docker.com/r/filebrowser/filebrowser) -- [Tailscale Docker Documentation](https://tailscale.com/kb/1282/docker) +![Initial admin password in the log](images/initial-admin-password-in-logs.png) + +## Links + +- [File Browser documentation](https://filebrowser.org/) +- [File Browser source code](https://github.com/filebrowser/filebrowser) diff --git a/services/flaresolverr/README.md b/services/flaresolverr/README.md index d5e7216b..bbe9352a 100644 --- a/services/flaresolverr/README.md +++ b/services/flaresolverr/README.md @@ -1,11 +1,33 @@ -# FlareSolverr with Tailscale Sidecar Configuration +# FlareSolverr -This Docker Compose configuration sets up FlareSolverr with Tailscale as a sidecar container to securely manage and route traffic for your Cloudflare bypass proxy over a private Tailscale network. By using Tailscale in a sidecar configuration, you can enhance the security of your FlareSolverr instance, ensuring that its API is only accessible within your Tailscale network. +[FlareSolverr](https://github.com/FlareSolverr/FlareSolverr) is a proxy server that solves Cloudflare challenges for other applications, such as Prowlarr. -## FlareSolverr +This stack runs FlareSolverr with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -FlareSolverr is an open-source proxy server to bypass Cloudflare and other anti-bot protections. It acts as a transparent bridge between your media automation tools (like Prowlarr or Jackett) and indexers that use Cloudflare, silently solving browser challenges in the background. This configuration leverages Tailscale to securely connect to your FlareSolverr API, ensuring that the proxy endpoint is protected from unauthorized access and that your instance is only accessible via your private Tailscale network. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | --------------------------------------- | +| Web interface | None | +| API | `https://flaresolverr..ts.net` | +| Service port | `8191` | +| Image | `ghcr.io/flaresolverr/flaresolverr` | +| Data | None | -In this setup, the tailscale-flaresolverr service runs Tailscale, which manages secure networking for the FlareSolverr service. The flaresolverr service uses the Tailscale network stack via Docker's network_mode: service:tailscale configuration. This setup ensures that FlareSolverr’s API (typically running on port 8191) is only accessible through the Tailscale network (or locally, if preferred), providing an extra layer of security and privacy for your self-hosted anti-bot proxy. +## Before you start + +Nothing beyond the [Quick Start](../../README.md#quick-start). + +## Deviations from the standard setup + +- **No web interface.** Tailscale Serve publishes the API of FlareSolverr. The address answers with a short status message. +- **No data folder.** FlareSolverr stores nothing on disk, so the stack has no volumes. +- **Optional settings.** `compose.yaml` passes `LOG_LEVEL`, `LOG_FILE`, `LOG_HTML`, and `CAPTCHA_SOLVER` to the container when you add them to `.env`. + +## First run + +Nothing to set up in FlareSolverr itself. Enter its address in the application that uses it. From another stack in this repository, use `http://:8191`. See the [DNS section of the standard setup](../../documentation/standard-setup.md#dns) for the use of names. + +## Links + +- [FlareSolverr documentation and source code](https://github.com/FlareSolverr/FlareSolverr) diff --git a/services/flatnotes/README.md b/services/flatnotes/README.md index 82c12647..2b24f470 100644 --- a/services/flatnotes/README.md +++ b/services/flatnotes/README.md @@ -1,19 +1,33 @@ -# Flatnotes with Tailscale Sidecar Configuration +# flatnotes -This Docker Compose configuration sets up **[Flatnotes](https://github.com/dullage/flatnotes)** with Tailscale as a sidecar container to securely manage and access your self-hosted note-taking application over a private Tailscale network. By integrating Tailscale, you can ensure that your Flatnotes instance remains private and accessible only to authorized devices within your Tailscale network. +[flatnotes](https://github.com/dullage/flatnotes) is a note-taking application that stores your notes as plain Markdown files. It has tags, full-text search, and no database. -## Flatnotes +This stack runs flatnotes with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Flatnotes](https://github.com/dullage/flatnotes) is a **lightweight, self-hosted note-taking app** that stores notes in plain text Markdown files. With a simple yet powerful interface, Flatnotes offers **tag-based organization**, **full-text search**, and a **distraction-free writing experience**. By integrating Tailscale, you can keep your notes private and secure, ensuring that only trusted devices can access them. +## At a glance -## Key Features +| Item | Value | +| ------------- | ------------------------------------------------- | +| Web interface | `https://flatnotes..ts.net` | +| Service port | `8080` | +| Image | `dullage/flatnotes` | +| Data | `./flatnotes-data` (your notes as Markdown files) | -- **Markdown-Based Notes** – Write and store notes in Markdown format for flexibility. -- **Tag-Based Organization** – Easily categorize and manage notes with tags. -- **Full-Text Search** – Quickly find notes with an efficient search function. -- **Self-Hosted Privacy** – Keep full control of your data without relying on third-party services. -- **Secure Access with Tailscale** – Restrict access to only authorized devices within your private network. +## Before you start -## Configuration Overview +Change these values in `.env`: -In this setup, the `tailscale-flatnotes` service runs Tailscale, which manages secure networking for the Flatnotes service. The `flatnotes` service uses the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This ensures that Flatnotes’ web interface and note storage are only accessible through the Tailscale network (or locally, if preferred), adding an extra layer of security and privacy for managing your notes. +- **`FLATNOTES_USERNAME` and `FLATNOTES_PASSWORD`.** The login of the web interface. The defaults are `user` and `changeMe!`. +- **`FLATNOTES_SECRET_KEY`.** A long random value that flatnotes uses to sign the login tokens. + +## Deviations from the standard setup + +None. + +## First run + +Open the web interface and log in with the username and password from `.env`. + +## Links + +- [flatnotes documentation and source code](https://github.com/dullage/flatnotes) diff --git a/services/forgejo/README.md b/services/forgejo/README.md index d53c84ad..095ba314 100644 --- a/services/forgejo/README.md +++ b/services/forgejo/README.md @@ -1,26 +1,39 @@ -# Forgejo with Tailscale Sidecar Configuration +# Forgejo -This Docker Compose configuration sets up [**Forgejo**](https://forgejo.org/) with Tailscale as a sidecar container, enabling secure access to your self-hosted Git service from anywhere on your private Tailscale network. With this setup, your Forgejo instance remains fully private and accessible only from authorized devices. +[Forgejo](https://forgejo.org/) is a Git service that you host yourself. It offers repositories, pull requests, issues, packages, and CI, and a community governs its development. -## Forgejo +This stack runs Forgejo with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[**Forgejo**](https://forgejo.org/) is a community-driven, self-hosted Git service inspired by the Esperanto word for *forge*. Designed as a lightweight and independent alternative to monopoly platforms, Forgejo offers Git hosting along with rich collaboration and project management tools. It is actively developed and governed by an open community, promising **Independent Free/Libre Software forever**. +## At a glance -## Key Features +| Item | Value | +| ------------- | ----------------------------------------------------------------- | +| Web interface | `https://forgejo..ts.net` | +| Service port | `3000` | +| Git over SSH | Port `22` on the Tailscale IP address of `forgejo` | +| Image | `codeberg.org/forgejo/forgejo:12` | +| Data | `./forgejo-data/data` (repositories, database, and configuration) | -* **Lightweight Deployment** – Runs smoothly on nearly any machine, from Raspberry Pi to cloud instances. -* **Project Management** – Built-in issues, pull requests, wikis, and kanban boards for seamless teamwork. -* **Publishing Tools** – Host software releases or publish via the built-in package registry (Docker, npm, etc.). -* **Customizable & Flexible** – Tweak configuration switches to adapt Forgejo to your exact needs. -* **Advanced Capabilities** – Organizations, permissions, CI/CD integration, code search, LDAP/OAuth support. -* **Privacy-First** – Minimal tracking and safe defaults to protect users and their data. -* **Federation (WIP)** – Ongoing work on ActivityPub integration to connect forges into a wider network. -* **Free & Open Source** – Licensed under GPL-3.0+, ensuring transparency and community ownership. +## Before you start -## Configuration Overview +Nothing beyond the [Quick Start](../../README.md#quick-start). -In this deployment, the `tailscale-forgejo` service runs the Tailscale client to establish a secure private network. The `forgejo` container uses `network_mode: service:tailscale` to route all traffic through the Tailscale interface. This ensures your Git service, web interface, and API endpoints are only accessible via Tailscale, preventing public exposure while still offering seamless remote access to your team. +## Deviations from the standard setup -## Reference Material +- **Git over SSH.** The SSH server of Forgejo listens on port `22` of the Tailscale IP address of the device. It does not use Tailscale Serve. +- **Time zone.** The stack mounts `/etc/timezone` and `/etc/localtime` of the Docker host read-only, in addition to `TZ`. +- **User and group.** The image uses `USER_UID` and `USER_GID` for the owner of the data, which `compose.yaml` sets to `1000`. -* [Youtube.com - Own Your Code Forever - A Private Git Server Setup Guide with Tailscale and Forgejo](https://www.youtube.com/watch?v=JcrcbkDGJuk) +## First run + +Open the web interface. Forgejo shows its installation page: + +1. Keep SQLite as the database, or enter the details of your own database. +2. Set the server domain to `forgejo..ts.net` and the base URL to `https://forgejo..ts.net/`. +3. Create the administrator account at the bottom of the page. If you skip this, the first account that registers becomes the administrator. + +## Links + +- [Forgejo documentation](https://forgejo.org/docs/latest/) +- [Forgejo source code](https://codeberg.org/forgejo/forgejo) +- [Video: a private Git server with Tailscale and Forgejo](https://www.youtube.com/watch?v=JcrcbkDGJuk) diff --git a/services/formbricks/README.md b/services/formbricks/README.md index bb44ed39..cf5bd57f 100644 --- a/services/formbricks/README.md +++ b/services/formbricks/README.md @@ -1,39 +1,44 @@ +# Formbricks -# Formbricks with Tailscale Sidecar Configuration +[Formbricks](https://formbricks.com/) is a survey and feedback platform. You build surveys, show them in your website, app, or by link, and analyse the answers on your own server. -This Docker Compose configuration sets up **Formbricks** with a Tailscale sidecar container, enabling secure access to your self-hosted user feedback and survey platform over your private Tailscale network. With this setup, your Formbricks instance remains **private and accessible only from authorized devices on your Tailnet**, keeping feedback data and analytics protected from public exposure. +This stack runs Formbricks with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -## Formbricks +## At a glance -[**Formbricks**](https://github.com/formbricks/formbricks) is an open-source, self-hosted alternative to tools like Typeform, Hotjar, and Google Forms. It allows you to collect **user feedback, surveys, NPS scores, and product insights** directly from your applications or websites, while maintaining full control over your data. +| Item | Value | +| ------------- | -------------------------------------------------------- | +| Web interface | `https://formbricks..ts.net` | +| Service port | `3000` | +| Images | `ghcr.io/formbricks/formbricks:4.9.7` | +| | `pgvector/pgvector:pg17` | +| | `valkey/valkey` | +| Data | `./formbricks-data/postgres` (PostgreSQL database) | +| | `./formbricks-data/redis` (Valkey data) | +| | `./formbricks-data/saml-connection` (SAML configuration) | -Formbricks is built with privacy, extensibility, and developer experience in mind, making it well-suited for internal tooling, SaaS products, and organizations that want insight without vendor lock-in. +## Before you start -## Key Features +Set these values in `.env`: -- 📝 **Surveys & Forms** – Create surveys, forms, and questionnaires with a modern UI. -- ⭐ **NPS & CSAT** – Measure Net Promoter Score and customer satisfaction. -- 🎯 **In-App Feedback** – Embed feedback widgets directly into your applications. -- 📊 **Analytics & Dashboards** – Analyze responses with built-in insights. -- 🔌 **API & Webhooks** – Integrate feedback data into external systems. -- 🔐 **Privacy-First** – Full data ownership through self-hosting. -- 🐳 **Docker-Ready** – Designed for containerized deployments. -- 📦 **Open Source** – Community-driven and extensible. +- **`TS_URL`.** The name of the device on your Tailnet, `formbricks..ts.net`. +- **`WEBAPP_URL`.** The address that you use to open Formbricks. The sample value is `http://${TS_URL}:3000`, which is the direct port on the Tailnet. To use the HTTPS address of Tailscale Serve, change it to `https://${TS_URL}`. `NEXTAUTH_URL` and `PUBLIC_URL` follow this value. +- **`NEXTAUTH_SECRET`, `ENCRYPTION_KEY`, and `CRON_SECRET`.** The sample values are public. Replace each with its own random value from `openssl rand -hex 32`. +- **The `SMTP_*` and `MAIL_FROM` values.** The details of your mail server, if Formbricks should send email. The sample values do not work. -## Why Self-Host? +## Deviations from the standard setup -Feedback data can include sensitive product insights, internal metrics, and personal information. Self-hosting Formbricks ensures **complete ownership and control over your data**, supports compliance requirements, and removes reliance on third-party SaaS platforms. Combined with Tailscale, Formbricks becomes a secure internal feedback system that is never exposed to the public internet. +- **Service name.** The application service is called `formbricks`, not `application`. +- **Extra containers.** The stack runs `postgres` and `redis` (Valkey). They use the default Compose network, and Formbricks reaches them by their service name through Docker's DNS. Keep `TS_ACCEPT_DNS` disabled, because MagicDNS cannot resolve these names. +- **Database password.** The password of the database is `postgres`, set in `compose.yaml` and in `DATABASE_URL` in `.env`. Change both to the same value before the first start. +- **Pinned version.** The stack pins Formbricks to `4.9.7`. Formbricks 5.0 and later also need the Cube, Hub, and SpiceDB services, which this stack does not include. See the [upstream Compose file](https://github.com/formbricks/formbricks/blob/main/docker/docker-compose.yml) before you upgrade. +- **Email verification and password reset are off.** `.env` sets `EMAIL_VERIFICATION_DISABLED="1"` and `PASSWORD_RESET_DISABLED="1"`, so Formbricks works without a mail server. -## Configuration Overview +## First run -In this deployment, a **Tailscale sidecar container** (for example `tailscale-formbricks`) runs the Tailscale client and joins your private Tailscale network. The main `formbricks` service uses: +The first start takes about three minutes, because Formbricks prepares its database. Then open the web interface at the address from `WEBAPP_URL` and create the first account, which becomes the owner of the organisation. -```plain -network_mode: service:tailscale -``` +## Links -This configuration routes all inbound and outbound traffic through the Tailscale interface, ensuring that the Formbricks admin UI, APIs, and feedback endpoints are accessible **only via your Tailscale network**. This keeps sensitive feedback data protected while still allowing secure access for authorized team members. - -## Image Version - -This configuration pins Formbricks to `4.9.7`. Formbricks 5.0 and later also require Cube, Hub, and SpiceDB services, which this stack does not include. See the [upstream Docker Compose file](https://github.com/formbricks/formbricks/blob/main/docker/docker-compose.yml) before you upgrade. +- [Formbricks self-hosting documentation](https://formbricks.com/docs/self-hosting/overview) +- [Formbricks source code](https://github.com/formbricks/formbricks) diff --git a/services/fossflow/README.md b/services/fossflow/README.md index 15336f70..6d91ff7f 100644 --- a/services/fossflow/README.md +++ b/services/fossflow/README.md @@ -1,20 +1,33 @@ -# FossFLOW with Tailscale Sidecar Configuration +# FossFLOW -This Docker Compose configuration sets up [FossFLOW](https://github.com/stan-smith/FossFLOW) with Tailscale as a sidecar container, enabling secure access to your visual workflow designer over your private Tailscale network. With this setup, FossFLOW remains fully self-hosted and is only accessible from authorized devices within your Tailnet. +[FossFLOW](https://hub.docker.com/r/stnsmith/fossflow) is a tool to draw isometric diagrams, for example of infrastructure and workflows. It only visualises a flow and does not run it. -## FossFLOW +The original repository of the project is no longer available on GitHub. [Abrar74774/FossFLOW](https://github.com/Abrar74774/FossFLOW) continues it. -FossFLOW is a free and open-source flow **visualization** tool. Unlike automation platforms like n8n or Node-RED, FossFLOW is focused purely on building and displaying visual representations of workflows—**not executing them**. It’s ideal for planning complex automations, designing data pipelines, or documenting logic in a clear, drag-and-drop interface. +This stack runs FossFLOW with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -## Key Features +## At a glance -* **Flow Visualizer** – Build directed graphs and flows using an intuitive UI. -* **No Execution** – FossFLOW is for visualization only, not for running workflows. -* **Node-Based Editor** – Easily represent logic, data sources, APIs, and more. -* **Export & Share** – Save flows as JSON and share them with others. -* **No Telemetry** – Fully local with zero tracking or analytics. -* **Secure with Tailscale** – Only accessible from your private Tailscale network. +| Item | Value | +| ------------- | ----------------------------------- | +| Web interface | `https://fossflow..ts.net` | +| Service port | `80` | +| Image | `stnsmith/fossflow` | +| Data | None on the host | -## Configuration Overview +## Before you start -This setup includes a `tailscale-fossflow` container running the Tailscale client to establish a secure connection. The `fossflow` container uses `network_mode: service:tailscale`, ensuring all traffic routes through Tailscale. This keeps your flow diagrams accessible only to authenticated devices within your Tailnet, with no exposure to the public internet. +Set `PUBLIC_URL` in `compose.yaml` to the address of the web interface, `https://fossflow..ts.net`. + +## Deviations from the standard setup + +- **Diagrams are not stored on the host.** FossFLOW saves diagrams on the server in `/data/diagrams` in the container, which this stack does not mount. They are lost when the container is recreated, for example after an image update. Export the diagrams that you want to keep. + +## First run + +Nothing to set up. Open the web interface. + +## Links + +- [FossFLOW image on Docker Hub](https://hub.docker.com/r/stnsmith/fossflow) +- [FossFLOW continuation, documentation and source code](https://github.com/Abrar74774/FossFLOW) diff --git a/services/freshrss/README.md b/services/freshrss/README.md index 48658bd8..dbb6e693 100644 --- a/services/freshrss/README.md +++ b/services/freshrss/README.md @@ -1,51 +1,49 @@ -# FreshRSS with Tailscale Sidecar Configuration +# FreshRSS -This Docker Compose configuration sets up [FreshRSS](https://freshrss.org/) with Tailscale as a sidecar container, enabling secure access to your self-hosted feed reader over a private Tailscale network. With this setup, your FreshRSS instance remains fully private and accessible only from devices on your Tailnet, over HTTPS. +[FreshRSS](https://freshrss.org/) is an RSS and Atom feed reader that you host yourself. It supports themes and extensions, and its Google Reader and Fever compatible API lets mobile and desktop clients synchronise with your server. -## FreshRSS +This stack runs FreshRSS with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[FreshRSS](https://github.com/FreshRSS/FreshRSS) is a self-hosted RSS and Atom feed aggregator. It is lightweight, powerful, and customizable through themes and extensions. It exposes a Google Reader-compatible and Fever-compatible API, so clients such as Reeder, NetNewsWire, Unread, and FeedMe can sync against your own server. +## At a glance -## Key Features +| Item | Value | +| ------------- | ------------------------------------------------------- | +| Web interface | `https://freshrss..ts.net` | +| Service port | `80` | +| Image | `freshrss/freshrss` | +| Data | `./freshrss-data/app/data` (configuration and database) | +| | `./freshrss-data/app/extensions` (extensions) | -- **Self-Hosted Feed Reading** – Your subscriptions, read state, and article archive stay on your own hardware. -- **Third-Party Client Sync** – Google Reader and Fever compatible APIs let third-party apps sync with your instance. -- **Extensible** – A large catalog of community themes and extensions. -- **Built-in Refresh Cron** – Feeds can be refreshed on a schedule inside the container, no host cron required. -- **Low Resource Usage** – Runs comfortably on a Raspberry Pi with the default SQLite database. -- **Private by Default with Tailscale** – No public exposure, no reverse proxies or port forwarding, and HTTPS handled by Tailscale Serve. +## Before you start -## Configuration Overview +Set these values in `.env` before the first start. FreshRSS uses them only while its data folder is empty. -In this deployment, the `tailscale-freshrss` service runs the Tailscale client and joins your Tailnet as the host `freshrss`. The `app-freshrss` service uses `network_mode: service:tailscale`. That means both containers share one network namespace. Tailscale Serve terminates HTTPS on port 443 and proxies to FreshRSS on `127.0.0.1:80` inside that shared namespace. +- **`TAILNET_NAME`.** Your Tailnet name with `.ts.net`. `compose.yaml` builds the base address of FreshRSS as `https://.`. +- **`ADMIN_USERNAME`, `ADMIN_PASSWORD`, and `ADMIN_EMAIL`.** The administrator account. +- **`ADMIN_API_PASSWORD`.** The password for clients that use the API. -## Prerequisites +Do not use `$`, backticks, or backslashes in these values. -- Docker and the Compose plugin, with your user in the `docker` group (or use `sudo`). -- `/dev/net/tun` available on the host and the `NET_ADMIN` capability, both already declared in `compose.yaml`. -- A Tailscale [auth key](https://console.tailscale.com/admin/settings/keys) from the web admin console (**Settings → Keys → Generate auth key**). Set it to "Pre-Approved" if that option appears. The key is used only for the initial registration — with `TS_AUTH_ONCE=true` and the persisted `ts/state` volume, restarts reuse the stored node state — so a single-use key is sufficient. Tagging the device disables key expiry, which avoids re-authentication after the default 180 days. -- HTTPS certificates [enabled for your Tailnet](https://console.tailscale.com/admin/dns) (**DNS → HTTPS Certificates**). Tailscale Serve cannot issue a certificate without it, and the container will start but never serve. +## Deviations from the standard setup -## Files to check +- **Unattended installation.** `FRESHRSS_INSTALL` and `FRESHRSS_USER` in `compose.yaml` install FreshRSS with SQLite and create the administrator at the first start. On later starts, FreshRSS reports `FreshRSS already installed; no change performed.` and ignores `.env`. +- **Trusted proxy.** `TRUSTED_PROXY=127.0.0.1` makes FreshRSS accept the client address that Tailscale Serve forwards. +- **Feed updates.** `CRON_MIN` in `.env` sets the minutes of each hour at which FreshRSS refreshes the feeds. +- **Health check.** The health check runs `./cli/health.php`, which requests `/api/`. If you disable the API in the web interface, the container reports unhealthy although the web interface works. -Please verify the following files and variables before deploying: +## First run -- `.env` — set `TS_AUTHKEY`, `TAILNET_NAME`, `TZ`, `ADMIN_USERNAME`, `ADMIN_PASSWORD`, `ADMIN_API_PASSWORD`, and `ADMIN_EMAIL`. -- `compose.yaml` — confirm the volume paths and the `Proxy` port in the `ts-serve` config. +Open the web interface and log in with the administrator account from `.env`. Change the passwords in the web interface from now on, not in `.env`. -## Usage Notes +## Configuration -- **First run only.** `FRESHRSS_INSTALL` and `FRESHRSS_USER` drive FreshRSS's unattended installer, and only take effect while the data directory is empty. On later starts the entrypoint reports `FreshRSS already installed; no change performed.` and ignores `.env`. Set the passwords before the first `docker compose up` and change them from the FreshRSS UI afterwards, not by editing `.env`. Avoid `$`, backticks, and backslashes in those first-run values — Compose and the entrypoint both interpret them. -- **`TAILNET_NAME` feeds the base URL.** `compose.yaml` builds `--base-url` as `https://${SERVICE}.${TAILNET_NAME}`, so include the `.ts.net` suffix. FreshRSS displays the value read-only under **Configuration → System**; to change it after the first run, use `docker compose exec application ./cli/reconfigure.php --base-url https://freshrss.example.ts.net`. -- **Health check.** The app health check runs `./cli/health.php`, which ships with the image and requests `/api/`. Disabling the API in the UI will mark the container unhealthy even though the web interface works. -- **Ports.** The `ports` block stays commented out; the Tailnet is the only way in. Uncommenting it publishes plain HTTP on the host and bypasses Tailscale entirely. Note `SERVICEPORT` is `80`, which often collides on the host. -- **MagicDNS.** Uncomment `TS_ACCEPT_DNS=true` only if the container itself must resolve other MagicDNS names, such as an external database. It is not needed for the default SQLite setup. +- **Change the base address.** FreshRSS shows the base address read-only under **Configuration** > **System**. To change it after the first start, run `docker compose exec application ./cli/reconfigure.php --base-url https://freshrss..ts.net`. +- **Local network access.** The `ports` block stays commented out. If you enable it, the stack publishes plain HTTP on port `80` of the Docker host, which is often in use. +- **MagicDNS.** `TS_ACCEPT_DNS=true` is only needed if FreshRSS itself must resolve MagicDNS names, such as an external database. The default SQLite setup does not need it. -## References +## Links -- [FreshRSS website](https://freshrss.org/) -- [FreshRSS on GitHub](https://github.com/FreshRSS/FreshRSS) +- [FreshRSS documentation](https://freshrss.github.io/FreshRSS/en/) - [FreshRSS Docker documentation](https://github.com/FreshRSS/FreshRSS/blob/edge/Docker/README.md) - [FreshRSS extensions](https://github.com/FreshRSS/Extensions) -- [Tailscale Serve documentation](https://tailscale.com/kb/1242/tailscale-serve) -- [Tailscale auth keys](https://tailscale.com/kb/1085/auth-keys) +- [FreshRSS source code](https://github.com/FreshRSS/FreshRSS) diff --git a/services/frigate/README.md b/services/frigate/README.md index 454141a9..e5e27374 100644 --- a/services/frigate/README.md +++ b/services/frigate/README.md @@ -1,40 +1,45 @@ -# Frigate with Tailscale Sidecar Configuration +# Frigate -This Docker Compose configuration sets up **Frigate** with Tailscale as a sidecar container, enabling secure, private access to your NVR and AI-based camera monitoring system over your Tailnet. +[Frigate](https://frigate.video/) is a network video recorder for IP cameras. It detects objects such as people, cars, and animals in real time and can use a GPU or an accelerator for the detection. -## Frigate +This stack runs Frigate with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Frigate](https://github.com/blakeblackshear/frigate) is an open-source network video recorder (NVR) designed for real-time object detection using AI. It integrates with IP cameras and leverages hardware acceleration (such as Google Coral, GPUs, or CPUs) to detect objects like people, cars, and animals with high efficiency. +## At a glance -Frigate is often paired with Tailscale to ensure that camera feeds, recordings, and detection events remain completely private, accessible only from trusted devices on your Tailnet rather than being exposed to the public internet. +| Item | Value | +| -------------- | ----------------------------------------------------------------------- | +| Web interface | `https://frigate..ts.net` | +| Service port | `8971` (HTTPS with a self-signed certificate) | +| Camera streams | Ports `8554` (RTSP) and `8555` (WebRTC, TCP and UDP) on the Docker host | +| Image | `ghcr.io/blakeblackshear/frigate:stable` | +| Data | `./frigate-data/config` (configuration and database) | +| | `./frigate-data/storage` (recordings, clips, and exports) | -## Configuration Overview +## Before you start -In this setup, the `tailscale-frigate` service runs Tailscale, which manages secure networking for Frigate. The `frigate` container shares the network stack using Docker’s `network_mode: service:tailscale`. +Change `FRIGATE_RTSP_PASSWORD` in `compose.yaml`. The sample value is `password`. -This ensures: +## Deviations from the standard setup -- No public ports are exposed by default -- Access is restricted to your Tailnet -- HTTPS access can be enabled via Tailscale Serve if desired +- **Serve forwards to HTTPS.** Frigate serves its authenticated web interface on port `8971` with a self-signed certificate. Tailscale Serve forwards to it with `https+insecure`. +- **Published host ports.** The `ports` block is active. It publishes the restream ports `8554` and `8555` on the Docker host, so that devices in your local network can reach the camera streams without Tailscale. +- **Privileged container.** The `application` container runs with `privileged: true`, so that Frigate can use the hardware of the Docker host for decoding and detection. +- **Shared memory and cache.** The stack gives Frigate 512 MB of shared memory and a 1 GB temporary file system for its cache. Increase the shared memory when you add many cameras. +- **Time zone.** The stack mounts `/etc/localtime` of the Docker host read-only, in addition to `TZ`. -## Key Features +## First run -- Real-time AI object detection (people, vehicles, animals, etc.) -- Local processing with optional hardware acceleration (Coral, GPU, CPU) -- RTSP camera support -- Event-based recording and snapshots -- Web UI for live view and playback -- MQTT integration for automation systems like Home Assistant +1. Frigate creates the user `admin` with a random password at the first start. Find it in the log: -## Files to Check + ```bash + docker logs app-frigate 2>&1 | grep -B1 "Password:" + ``` -Please review: +2. Open the web interface and log in. +3. Add your cameras in the configuration editor of the web interface. Frigate stores the configuration in `./frigate-data/config/config.yml`. -- `.env` → Ensure `TS_AUTHKEY` is set +## Links -## Useful Links - -- Frigate Documentation: -- GitHub Repository: -- Hardware Acceleration Guide: +- [Frigate documentation](https://docs.frigate.video/) +- [Frigate hardware guide](https://docs.frigate.video/frigate/hardware) +- [Frigate source code](https://github.com/blakeblackshear/frigate) diff --git a/services/ghost/README.md b/services/ghost/README.md index e47a8313..cc83c869 100644 --- a/services/ghost/README.md +++ b/services/ghost/README.md @@ -1,21 +1,36 @@ -# Ghost with Tailscale Sidecar Configuration +# Ghost -This Docker Compose configuration sets up **[Ghost](https://github.com/TryGhost/Ghost)** with Tailscale as a sidecar container to securely manage and access your self-hosted publishing platform over a private Tailscale network. By integrating Tailscale, you can ensure that your Ghost instance remains private and accessible only to authorized devices within your Tailscale network. +[Ghost](https://ghost.org/) is a publishing platform for blogs, newsletters, and online publications. -## Ghost +This stack runs Ghost with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Ghost](https://github.com/TryGhost/Ghost) is a modern, open-source publishing platform designed for professional blogs, newsletters, and online publications. It provides a sleek, minimalist editor, built-in SEO features, and powerful customization options. By integrating Tailscale, your Ghost instance remains secure and accessible only to authorized users, ensuring that your content is managed in a private environment. +## At a glance -## Key Features +| Item | Value | +| ------------- | --------------------------------------------------------------------------------------------------- | +| Web interface | `https://ghost..ts.net` (site) and `https://ghost..ts.net/ghost` (administration) | +| Service port | `2368` | +| Images | `ghost:5-alpine` | +| | `mysql:8.0` | +| Data | `./ghost-data/ghost` (themes, images, and settings) | +| | `./ghost-data/db` (MySQL database) | -- **Minimalist & Fast** – A lightweight, streamlined writing experience for bloggers and content creators. -- **Built-in SEO & Analytics** – Optimize content for search engines and track performance effortlessly. -- **Customizable Themes & Integrations** – Extend Ghost with themes, memberships, and integrations. -- **Self-Hosted Privacy** – Maintain full control over your content with a locally hosted instance. -- **Secure Access with Tailscale** – Restrict access to only authorized devices within your private network. +## Before you start -## Configuration Overview +- **Set `GHOST_URL` in `.env`.** Use the address of the site, `https://ghost..ts.net`. Ghost does not start with the sample value and reports `Invalid URL`. +- **Change the database password.** `compose.yaml` uses the password `example` for the MySQL `root` user, in `database__connection__password` and in `MYSQL_ROOT_PASSWORD`. Replace both with the same value of your own before the first start. -In this setup, the `tailscale-ghost` service runs Tailscale, which manages secure networking for the Ghost service. The `ghost` service uses the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This ensures that Ghost’s web interface and publishing tools are only accessible through the Tailscale network (or locally, if preferred), adding an extra layer of security and privacy to your publishing workflow. +## Deviations from the standard setup -Set `GHOST_URL` in `.env` to the HTTPS hostname that you use on your Tailnet. Ghost listens on port `2368`, and Tailscale Serve forwards HTTPS traffic to that port. +- **Extra container.** The stack runs a `db` container with MySQL, named `db-ghost`. It uses the default Compose network, and Ghost reaches it by its service name through Docker's DNS. Keep `TS_ACCEPT_DNS` disabled, because MagicDNS cannot resolve that name. +- **Service port.** Ghost listens on port `2368`. `SERVICEPORT` in `.env` is only the host port of the optional `ports` block. + +## First run + +Open `https://ghost..ts.net/ghost` and create the first account, which becomes the owner of the site. + +## Links + +- [Ghost documentation](https://ghost.org/docs/) +- [Ghost Docker image](https://hub.docker.com/_/ghost) +- [Ghost source code](https://github.com/TryGhost/Ghost) diff --git a/services/gitea/README.md b/services/gitea/README.md index f8852494..add734e6 100644 --- a/services/gitea/README.md +++ b/services/gitea/README.md @@ -1,19 +1,39 @@ -# Gitea with Tailscale Sidecar Configuration +# Gitea -This Docker Compose configuration sets up [Gitea](https://gitea.com/) with Tailscale as a sidecar container, enabling secure access to your self-hosted Git forge via your private Tailnet. With this setup, your Gitea instance remains fully private and accessible only from authorized Tailscale devices. +[Gitea](https://about.gitea.com/) is a lightweight Git service that you host yourself. It offers repositories, pull requests, issues, packages, and CI. -## Gitea +This stack runs Gitea with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Gitea](https://gitea.com/) is a lightweight, self-hosted Git service that provides repository hosting, pull requests, issue tracking, and more. It is designed for easy deployment and minimal operational overhead, making it a great choice for private Git hosting on homelabs and small teams. +## At a glance -## Key Features +| Item | Value | +| ------------- | --------------------------------------------------------------- | +| Web interface | `https://gitea..ts.net` | +| Service port | `3000` | +| Git over SSH | Port `22` on the Tailscale IP address of `gitea` | +| Image | `docker.gitea.com/gitea` | +| Data | `./gitea-data/data` (repositories, database, and configuration) | -* **Lightweight Deployment** – Runs smoothly on nearly any machine, from Raspberry Pi to cloud instances. -* **Repository Management** – Full Git repository hosting with web interface. -* **Collaboration Tools** – Pull requests, issues, and wiki support for team collaboration. -* **Self-Hosted** – Complete control over your code and data. -* **Private by Default with Tailscale** – Secured with Tailscale, accessible only to your authorized devices. +## Before you start -## Configuration Overview +Nothing beyond the [Quick Start](../../README.md#quick-start). -In this deployment, the `tailscale-gitea` service runs the Tailscale client to establish a secure private network. The `gitea` container uses `network_mode: service:tailscale` to route all traffic through the Tailscale interface. This ensures your Git service, web interface, and API endpoints are only accessible via Tailscale, preventing public exposure while still offering seamless remote access to your team. +## Deviations from the standard setup + +- **Git over SSH.** The SSH server of Gitea listens on port `22` of the Tailscale IP address of the device. It does not use Tailscale Serve. +- **Time zone.** The stack mounts `/etc/timezone` and `/etc/localtime` of the Docker host read-only, in addition to `TZ`. +- **User and group.** The image uses `USER_UID` and `USER_GID` for the owner of the data, which `compose.yaml` sets to `1000`. +- **Fixed data folder.** The data folder is always `./gitea-data`, also when you change `SERVICE` in `.env`. + +## First run + +Open the web interface. Gitea shows its installation page: + +1. Keep SQLite as the database, or enter the details of your own database. +2. Set the server domain to `gitea..ts.net` and the base URL to `https://gitea..ts.net/`. +3. Create the administrator account at the bottom of the page. If you skip this, the first account that registers becomes the administrator. + +## Links + +- [Gitea documentation](https://docs.gitea.com/) +- [Gitea source code](https://github.com/go-gitea/gitea) diff --git a/services/gitsave/README.md b/services/gitsave/README.md index f9c6e5e9..0ec06e86 100644 --- a/services/gitsave/README.md +++ b/services/gitsave/README.md @@ -1,20 +1,34 @@ -# GitSave with Tailscale Sidecar Configuration +# GitSave -This Docker Compose configuration sets up [**GitSave**](https://github.com/TimWitzdam/GitSave) with Tailscale as a sidecar container, enabling secure access to your self-hosted GitHub repository backup solution from anywhere on your private Tailscale network. With this setup, your GitSave instance remains fully private and accessible only from authorized devices. +[GitSave](https://github.com/TimWitzdam/GitSave) backs up your Git repositories on a schedule. You add the repositories in a web interface and GitSave keeps copies of them on your server. -## GitSave +This stack runs GitSave with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[**GitSave**](https://github.com/TimWitzdam/GitSave) is a self-hosted tool for automatically backing up your GitHub repositories. It runs as a lightweight web service with a simple REST API and can be scheduled or triggered manually. Designed for developers, teams, and organizations who want to keep a secure copy of their code outside GitHub, GitSave ensures your projects remain safe and accessible under your own control. +## At a glance -## Key Features +| Item | Value | +| ------------- | ------------------------------------------------------- | +| Web interface | `https://gitsave..ts.net` | +| Service port | `3000` | +| Image | `timwitzdam/gitsave` | +| Data | `./gitsave-data/gitsave` (database) | +| | `./gitsave-data/backups` (backups of your repositories) | -* **Automated Backups** – Regularly back up all your GitHub repositories with minimal setup. -* **REST API Interface** – Trigger backups or manage configurations programmatically. -* **Simple Configuration** – Connect with your GitHub account via a personal access token. -* **Dockerized Deployment** – Run in a containerized environment for easy setup and portability. -* **Lightweight & Fast** – Written in Go for speed and efficiency with minimal resource usage. -* **Self-Hosted & Secure** – Maintain full control of your backup data on your own infrastructure. +## Before you start -## Configuration Overview +Replace these values in `.env`: -In this deployment, the `tailscale-gitsave` service runs the Tailscale client to establish a secure private network. The `gitsave` container uses `network_mode: service:tailscale` to route all traffic through the Tailscale interface. This ensures that your GitHub backup service and its API endpoints are only accessible via Tailscale, preventing public exposure. +- **`JWT_SECRET`.** A long random value. +- **`ENCRYPTION_SECRET`.** A random value of exactly 32 characters, for example from `openssl rand -hex 16`. GitSave does not start with the sample value and reports `ENCRYPTION_SECRET must be 32 bytes`. + +## Deviations from the standard setup + +None. + +## First run + +Open the web interface and create the first account. + +## Links + +- [GitSave documentation and source code](https://github.com/TimWitzdam/GitSave) diff --git a/services/glance/README.md b/services/glance/README.md index 62c90bb1..02f54546 100644 --- a/services/glance/README.md +++ b/services/glance/README.md @@ -1,13 +1,35 @@ -# Glance with Tailscale Sidecar Configuration +# Glance -This Docker Compose configuration sets up [Glance](https://github.com/glanceapp/glance) with Tailscale as a sidecar container to securely access your system monitoring dashboard over a private Tailscale network. By using Tailscale in a sidecar configuration, you can enhance the security and privacy of your Glance instance, ensuring that it is only accessible within your Tailscale network. +[Glance](https://github.com/glanceapp/glance) is a dashboard that puts your feeds on one page, such as RSS, weather, markets, and the status of your services. -## Glance +This stack runs Glance with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Glance](https://github.com/glanceapp/glance) is a sleek, real-time dashboard for monitoring your system metrics, Docker containers, and other self-hosted services. It offers a clean and responsive interface that consolidates key system stats and service statuses in one place. This configuration uses Tailscale to securely expose your Glance instance, keeping it protected from the public internet and accessible only within your private Tailscale network. +## At a glance -To install Glance properly, make sure to add the files glance.yml and home.yml to the config folder. The contents of these files can be found [at their Github repo](https://github.com/glanceapp/docker-compose-template/tree/main/root/config). Also add the file user.css to the assets folder which can be found [at their Github repo](https://github.com/glanceapp/docker-compose-template/tree/main/root/assets). +| Item | Value | +| ------------- | ---------------------------------------------------------- | +| Web interface | `https://glance..ts.net` | +| Service port | `8080` | +| Image | `glanceapp/glance` | +| Data | `./glance-data/config` (configuration files) | +| | `./glance-data/assets` (custom assets, such as `user.css`) | -## Configuration Overview +## Before you start -In this setup, the `tailscale-glance` service runs Tailscale, which provides secure networking for the Glance service. The `glance` service uses the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This ensures that the Glance dashboard is only accessible through the Tailscale network (or locally, if desired), adding a robust layer of privacy and security to your self-hosted monitoring setup. +Glance needs its configuration files before the first start. Without `glance.yml`, the `application` container keeps restarting. + +1. Add `glance.yml` and `home.yml` to `./glance-data/config`. You find both in the [`config` folder of the Glance template](https://github.com/glanceapp/docker-compose-template/tree/main/root/config). +2. Add `user.css` to `./glance-data/assets`. You find it in the [`assets` folder of the Glance template](https://github.com/glanceapp/docker-compose-template/tree/main/root/assets). + +## Deviations from the standard setup + +None. + +## First run + +Glance has no login by default. Open the web interface, then edit the files in `./glance-data/config` to build your pages. + +## Links + +- [Glance configuration documentation](https://github.com/glanceapp/glance/blob/main/docs/configuration.md) +- [Glance source code](https://github.com/glanceapp/glance) diff --git a/services/gokapi/README.md b/services/gokapi/README.md index a1289ac4..fd2efdf3 100644 --- a/services/gokapi/README.md +++ b/services/gokapi/README.md @@ -1,11 +1,32 @@ -# Gokapi with Tailscale Sidecar Configuration +# Gokapi -This Docker Compose configuration sets up [Gokapi](https://github.com/Forceu/Gokapi) with Tailscale as a sidecar container to securely manage and access your lightweight file-sharing service over a private Tailscale network. By using Tailscale in a sidecar configuration, you can enhance the security and privacy of your Gokapi instance, ensuring that it is only accessible within your Tailscale network. +[Gokapi](https://github.com/Forceu/Gokapi) is a file sharing server. You upload a file and share a link that expires after a number of downloads or days. -## Gokapi +This stack runs Gokapi with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Gokapi](https://github.com/Forceu/Gokapi) is a lightweight, self-hosted file-sharing platform designed to provide a simple and secure way to share files with others. It features an intuitive web interface, token-based sharing, and the ability to control file expiry and download limits. This configuration leverages Tailscale to securely connect to your Gokapi instance, ensuring that your file-sharing activities remain private and protected from unauthorized access. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | --------------------------------------------- | +| Web interface | `https://gokapi..ts.net` | +| Service port | `53842` | +| Image | `f0rc3/gokapi` | +| Data | `./gokapi-data/gokapi-data` (uploaded files) | +| | `./gokapi-data/gokapi-config` (configuration) | -In this setup, the `tailscale-gokapi` service runs Tailscale, which manages secure networking for the Gokapi service. The `gokapi` service uses the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This setup ensures that Gokapi's web interface and file-sharing services are only accessible through the Tailscale network (or locally, if preferred), providing an additional layer of security and privacy for your file-sharing solution. +## Before you start + +Nothing beyond the [Quick Start](../../README.md#quick-start). + +## Deviations from the standard setup + +None. + +## First run + +Open `https://gokapi..ts.net/setup`. The setup wizard asks for the authentication method, the administrator account, the storage, and the public address of the server. Until you finish it, the web interface only shows a maintenance message. + +## Links + +- [Gokapi documentation](https://gokapi.readthedocs.io/en/latest/) +- [Gokapi source code](https://github.com/Forceu/Gokapi) diff --git a/services/gotify/README.md b/services/gotify/README.md index e846b7e6..b8f0ab46 100644 --- a/services/gotify/README.md +++ b/services/gotify/README.md @@ -1,19 +1,33 @@ -# Gotify with Tailscale Sidecar Configuration +# Gotify -This Docker Compose configuration sets up [Gotify](https://github.com/gotify/server) with Tailscale as a sidecar container, enabling secure access to your notification server from anywhere on your private Tailscale network. With this setup, your Gotify instance remains completely private and protected, accessible only to your authorized devices. +[Gotify](https://gotify.net/) is a server to send and receive notifications. Your scripts and applications post a message over HTTP, and the web interface and the Android app show it in real time. -## Gotify +This stack runs Gotify with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Gotify](https://github.com/gotify/server) is a simple server for sending and receiving messages in real-time. It's a self-hosted solution perfect for getting notifications from various services directly to your device. Gotify is lightweight, easy to set up, and designed to work seamlessly with your existing infrastructure. +## At a glance -## Key Features +| Item | Value | +| ------------- | --------------------------------- | +| Web interface | `https://gotify..ts.net` | +| Service port | `80` | +| Image | `gotify/server` | +| Data | `./gotify-data/app/data` | -* **Real-Time Notifications** – Receive instant messages from your applications. -* **Simple Setup** – Easy to deploy and configure. -* **Customizable Clients** – Works with multiple clients on different platforms. -* **Self-Hosted** – Full control over your notification data. -* **Private by Default with Tailscale** – Secured with Tailscale, accessible only to you. +## Before you start -## Configuration Overview +Change `GOTIFY_DEFAULTUSER_PASS` in `compose.yaml`. It sets the password of the user `admin` that Gotify creates at the first start, and the sample value is `admin`. -In this deployment, the `tailscale-gotify` service runs the Tailscale client to establish a secure private network. The `gotify` container uses `network_mode: service:tailscale` to route its traffic through the Tailscale interface. This ensures that the Gotify web UI and backend services are only reachable via your Tailscale network, keeping your notifications safe from public exposure. +## Deviations from the standard setup + +None. + +## First run + +Open the web interface and log in with username `admin` and the password from `GOTIFY_DEFAULTUSER_PASS`. Gotify uses this value only at the first start, so change the password in the web interface afterwards. + +In the Gotify app, use `https://gotify..ts.net` as the server address. The device must be connected to your Tailnet. + +## Links + +- [Gotify documentation](https://gotify.net/docs/) +- [Gotify source code](https://github.com/gotify/server) diff --git a/services/grampsweb/README.md b/services/grampsweb/README.md index 6239ee2b..ecb44263 100644 --- a/services/grampsweb/README.md +++ b/services/grampsweb/README.md @@ -1,22 +1,37 @@ -# Gramps Web with Tailscale Sidecar Configuration +# Gramps Web -This Docker Compose configuration sets up [**Gramps Web**](https://github.com/gramps-project/gramps-web) with Tailscale as a sidecar container, enabling secure access to your self-hosted genealogy platform from anywhere on your private Tailscale network. With this setup, your Gramps Web instance remains fully private and accessible only from authorized devices. +[Gramps Web](https://www.grampsweb.org/) is a web application to browse and edit your family tree together with others. It works with the data of the Gramps desktop application. -## Gramps Web +This stack runs Gramps Web with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[**Gramps Web**](https://github.com/gramps-project/gramps-web) is an open-source, self-hosted web application for collaborative browsing and editing of genealogical data. It provides a modern, mobile-friendly interface to your family tree, with full interoperability with the Gramps Desktop application. Designed for individuals, families, and research groups, Gramps Web makes it easy to share, visualize, and enrich family history data while keeping full control over your information. +## At a glance -## Key Features +| Item | Value | +| ------------- | ----------------------------------------------------------------------------------------------------------------- | +| Web interface | `https://grampsweb..ts.net` | +| Service port | `5000` | +| Images | `ghcr.io/gramps-project/grampsweb` | +| | `docker.io/library/redis:7.2.4-alpine` | +| Data | `./grampsweb-data/gramps_db` (family tree database) | +| | `./grampsweb-data/gramps_media` (media files) | +| | `./grampsweb-data/gramps_users` (user database) | +| | `./grampsweb-data/gramps_secret` (secret key) | +| | `./grampsweb-data/gramps_index`, `gramps_thumb_cache`, `gramps_cache`, and `gramps_tmp` (search index and caches) | -* **Collaborative Editing** – Multiple users can view and edit the same family tree with role-based permissions. -* **Interactive Charts and Maps** – Explore family relationships through dynamic ancestor, descendant, and hourglass charts, plus integrated mapping with historical overlays. -* **AI-Powered Chat** – Ask questions about your family tree using natural language, with AI providing context-aware answers. -* **Media and Face Tagging** – Store and manage media files, with automatic face detection and tagging to link people to photos. -* **Search and Reporting** – Perform full-text searches and generate printable reports directly in the browser. -* **Bi-Directional Sync with Gramps Desktop** – Keep online and offline databases in sync using the Gramps Web Sync add-on. -* **Privacy Controls** – Mark individuals or events as private and filter sensitive data from public views. -* **Self-Hosted & Open Source** – Run on your own infrastructure with Docker, keeping your data under your control. +## Before you start -## Configuration Overview +Nothing beyond the [Quick Start](../../README.md#quick-start). -In this deployment, the `tailscale-grampsweb` service runs the Tailscale client to establish a secure private network. The `grampsweb` container uses `network_mode: service:tailscale` to route all traffic through the Tailscale interface. This ensures that your genealogy database, charts, and administration interface are only accessible via Tailscale, preventing public exposure. +## Deviations from the standard setup + +- **Extra containers.** The stack runs `grampsweb_celery`, a worker for background tasks that uses the same image and the same data folders, and `grampsweb_redis`. The worker uses the network of the `tailscale` container, like Gramps Web itself. Redis uses the default Compose network, and Gramps Web reaches it by its service name through Docker's DNS. Keep `TS_ACCEPT_DNS` disabled, because MagicDNS cannot resolve that name. +- **Tree name.** `GRAMPSWEB_TREE` in `compose.yaml` sets the name of the family tree to `Gramps Web`. + +## First run + +Open the web interface. Gramps Web asks you to create the owner account. Then start an empty tree or import a Gramps XML file. + +## Links + +- [Gramps Web documentation](https://www.grampsweb.org/) +- [Gramps Web source code](https://github.com/gramps-project/gramps-web) diff --git a/services/haptic/README.md b/services/haptic/README.md index e82b60e9..55b8c013 100644 --- a/services/haptic/README.md +++ b/services/haptic/README.md @@ -1,19 +1,30 @@ -# Haptic with Tailscale Sidecar Configuration +# Haptic -This Docker Compose configuration sets up **[Haptic](https://github.com/chroxify/haptic)** with Tailscale as a sidecar container to securely manage and access your self-hosted bookmark manager over a private Tailscale network. By integrating Tailscale, you can ensure that your Haptic instance remains private and accessible only to authorized devices within your Tailscale network. +[Haptic](https://github.com/chroxify/haptic) is a local-first editor for your Markdown notes. The web version keeps your notes in the browser. -## Haptic +This stack runs Haptic with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Haptic](https://github.com/chroxify/haptic) is a modern, self-hosted bookmark manager designed for simplicity, speed, and privacy. It allows users to organize, search, and access saved links efficiently while providing a clean and user-friendly interface. With Haptic, you can take full control of your bookmarks without relying on third-party services. By integrating Tailscale, you can further secure your Haptic instance by ensuring access is restricted to authorized devices within your private network. +## At a glance -## Key Features +| Item | Value | +| ------------- | --------------------------------- | +| Web interface | `https://haptic..ts.net` | +| Service port | `80` | +| Image | `chroxify/haptic-web` | +| Data | None | -- **Self-Hosted Bookmark Management** – Organize and store bookmarks securely. -- **Full-Text Search** – Quickly find saved bookmarks with an intuitive search function. -- **Minimalist & Fast** – Designed for speed and usability without unnecessary complexity. -- **Privacy-Focused** – Keep your bookmarks safe and private with a self-hosted solution. -- **Secure Access with Tailscale** – Restrict access to only authorized devices within your private network. +## Before you start -## Configuration Overview +Nothing beyond the [Quick Start](../../README.md#quick-start). -In this setup, the `tailscale-haptic` service runs Tailscale, which manages secure networking for the Haptic service. The `haptic` service uses the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This ensures that Haptic’s web interface is only accessible through the Tailscale network (or locally, if preferred), adding an extra layer of security and privacy for managing your bookmarks. +## Deviations from the standard setup + +- **No data folder.** The stack has no volumes. Haptic stores your notes in the browser of each device, not on the server. + +## First run + +Nothing to set up. Open the web interface. + +## Links + +- [Haptic documentation and source code](https://github.com/chroxify/haptic) diff --git a/services/hemmelig/README.md b/services/hemmelig/README.md index b03c880b..662a9dd7 100644 --- a/services/hemmelig/README.md +++ b/services/hemmelig/README.md @@ -1,31 +1,36 @@ -# Hemmelig.app with Tailscale Sidecar Configuration +# Hemmelig -This Docker Compose configuration sets up **Hemmelig.app** with a Tailscale sidecar container, enabling secure access to your private encrypted secret-sharing platform over your Tailscale network. With this setup, your instance will be **private and reachable only by your authorized Tailscale devices**, ensuring truly confidential communication and secret exchange. +[Hemmelig](https://github.com/HemmeligOrg/Hemmelig.app) shares secrets such as passwords and API keys with a link. It encrypts the secret in the browser, and the secret is deleted after it is read or when it expires. -## Hemmelig.app +The upstream repository is archived, so the project gets no further updates. -[**Hemmelig.app**](https://github.com/HemmeligOrg/Hemmelig.app) is an open-source encrypted sharing platform designed for securely transmitting sensitive information such as passwords, confidential messages, API keys, or other private data. All encryption is performed client-side using strong cryptography (TweetNaCl), meaning **your secrets are encrypted before ever leaving the user’s browser and the server never sees the plaintext**. +This stack runs Hemmelig with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -## Key Features +## At a glance -- 🔐 **Zero-Knowledge Encryption** – All data encrypted client-side; the server only stores ciphertext. -- ⏳ **Self-Destructing Secrets** – Secrets can expire after time or a specific number of views. -- 🛡 **Optional Password Protection** – Add another layer of protection to shared secrets. -- 🌍 **IP Restrictions** – Restrict who can view the secret based on IP range. -- 📁 **Encrypted File Uploads** – Support for sharing files securely (when enabled). -- 🪪 **Rich Sharing Options** – Includes QR code support and metadata controls. -- 📦 **Self-Hosted Friendly** – Easy Docker deployment with persistent storage and SQLite backend. +| Item | Value | +| ------------- | ------------------------------------------- | +| Web interface | `https://hemmelig..ts.net` | +| Service port | `3000` | +| Image | `hemmeligapp/hemmelig:v7` | +| Data | `./hemmelig-data/database` (database) | +| | `./hemmelig-data/uploads` (encrypted files) | -## Why Self-Host? +## Before you start -While a public SaaS instance of Hemmelig (e.g., hemmelig.app) exists, **self-hosting gives you full control over your data, compliance, and uptime** — especially important if you’re sharing highly sensitive company secrets or keys. Combining it with Tailscale ensures the service isn’t publicly reachable at all, but instead safely accessible only by your team. +Change these values in `compose.yaml`: -## Configuration Overview +- **`BETTER_AUTH_URL` and `HEMMELIG_BASE_URL`.** The address of the web interface, `https://hemmelig..ts.net`. The sample value is `https://secrets.example.com`. +- **`BETTER_AUTH_SECRET`.** A random value of at least 32 characters. The sample value is public. -In this deployment, a **Tailscale sidecar container** (e.g., `tailscale-hemmelig`) runs the Tailscale client and joins your private Tailscale network. The main `hemmelig` service uses: +## Deviations from the standard setup -```plain -network_mode: service:tailscale -``` +None. -This effectively **routes all traffic through the Tailscale network interface**, making the app private and unreachable from the public Internet while still accessible to any device on your Tailscale network. Remote team members can securely access the Hemmelig web UI, API, and encryption features over Tailscale without exposing the app publicly. +## First run + +Open the web interface. Hemmelig asks you to create the first account. + +## Links + +- [Hemmelig documentation and source code](https://github.com/HemmeligOrg/Hemmelig.app) diff --git a/services/homarr/README.md b/services/homarr/README.md index a0ec402e..b39bf945 100644 --- a/services/homarr/README.md +++ b/services/homarr/README.md @@ -1,21 +1,35 @@ -# Homarr with Tailscale Sidecar Configuration +# Homarr -This Docker Compose configuration sets up [Homarr](https://github.com/ajnart/homarr) with Tailscale as a sidecar container to securely manage and access your dashboard over a private Tailscale network. By using Tailscale in a sidecar configuration, you can enhance the security and privacy of your Homarr instance, ensuring that it is only accessible within your Tailscale network. +[Homarr](https://homarr.dev/) is a dashboard for your services. It shows your applications on one page and integrates with many of them to display live information. -## Homarr +This stack runs Homarr with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Homarr](https://github.com/ajnart/homarr) is an open-source, self-hosted dashboard that integrates with all your self-hosted services, providing a centralized location to manage and access your apps, notifications, and more. It supports customization and can be extended with various plugins and integrations. This configuration leverages Tailscale to securely connect to your Homarr instance, ensuring that your dashboard interface is protected from unauthorized access and that your instance is accessible only via your private Tailscale network. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | --------------------------------- | +| Web interface | `https://homarr..ts.net` | +| Service port | `7575` | +| Image | `ghcr.io/homarr-labs/homarr` | +| Data | `./homarr-data/appdata` | -In this setup, the tailscale-homarr service runs Tailscale, which manages secure networking for the Homarr service. The homarr service uses the Tailscale network stack via Docker's network_mode: service:tailscale configuration. This setup ensures that Homarr’s web interface is only accessible through the Tailscale network (or locally, if preferred), providing an extra layer of security and privacy for your self-hosted dashboard. +## Before you start -## Files to check +Set `SECRET_ENCRYPTION_KEY` in `.env` to a hex key of 64 characters. Generate one with `openssl rand -hex 32`. Compose stops with an error if it is empty. -Please check the following contents for validity as some variables need to be defined upfront. +## Deviations from the standard setup -- `.env` - - Required: `TS_AUTHKEY` - - Required: `SECRET_ENCRYPTION_KEY`, a 64-character hex key. Generate it with `openssl rand -hex 32`. Compose stops with an error if it is empty. +None. -If you previously set `SECRET_ENCRYPTION_KEY` in `compose.yaml`, move that value to `.env`. A new key cannot decrypt the integration secrets that Homarr already stored. +## First run + +Open the web interface and follow the onboarding. Homarr asks you to create the administrator account. + +## Upgrading + +If you set `SECRET_ENCRYPTION_KEY` in `compose.yaml` before, move that value to `.env`. A new key cannot decrypt the secrets of the integrations that Homarr already stored. + +## Links + +- [Homarr documentation](https://homarr.dev/docs/getting-started/) +- [Homarr source code](https://github.com/homarr-labs/homarr) diff --git a/services/home-assistant/README.md b/services/home-assistant/README.md index fc207c21..e2eda81c 100644 --- a/services/home-assistant/README.md +++ b/services/home-assistant/README.md @@ -1,42 +1,46 @@ -# Home Assistant with Tailscale Sidecar Configuration +# Home Assistant -This Docker Compose configuration sets up **[Home Assistant](https://github.com/home-assistant/)** with Tailscale as a sidecar container to securely manage and access your smart home automation platform over a private Tailscale network. By integrating Tailscale, you can ensure that your Home Assistant instance remains private and accessible only to authorized devices within your Tailscale network. +[Home Assistant](https://www.home-assistant.io/) is a home automation platform. It controls and automates the smart devices in your home from one interface and runs locally. -## Home Assistant +This stack runs Home Assistant with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Home Assistant](https://github.com/home-assistant/) is an open-source home automation platform that allows you to control and automate smart devices from a unified interface. With support for thousands of integrations, it provides powerful automation capabilities and privacy-focused self-hosted control over your smart home. Pairing Home Assistant with Tailscale ensures a secure, remote-accessible smart home without exposing it to the public internet. +## At a glance -## Key Features +| Item | Value | +| ------------- | ---------------------------------------------- | +| Web interface | `https://home-assistant..ts.net` | +| Service port | `8123` | +| Image | `ghcr.io/home-assistant/home-assistant:stable` | +| Data | `./home-assistant-data/config` | -- **Local Control & Privacy** – Self-hosted and privacy-focused, keeping your data in your home. -- **Extensive Integrations** – Supports thousands of smart home devices and services. -- **Automation & Customization** – Create complex automations with YAML or visual editors. -- **Secure Remote Access** – Pair with Tailscale to safely access your Home Assistant instance from anywhere. +## Before you start -## Configuration Overview +Nothing beyond the [Quick Start](../../README.md#quick-start). -In this setup, the `tailscale-homeassistant` service runs Tailscale, which manages secure networking for the Home Assistant service. The `homeassistant` service uses the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This ensures that Home Assistant’s web interface and smart home control features are only accessible through the Tailscale network (or locally, if preferred), adding an extra layer of security and privacy for your home automation system. +## Deviations from the standard setup -## Troubleshooting +- **Privileged container.** The `application` container runs with `privileged: true`, so that Home Assistant can use the devices of the Docker host, such as USB sticks for Zigbee or Z-Wave. +- **D-Bus.** The stack mounts `/run/dbus` of the Docker host read-only, which the Bluetooth integration needs. +- **Time zone.** The stack mounts `/etc/localtime` of the Docker host read-only, in addition to `TZ`. +- **Not on your local network.** Home Assistant uses the network of the `tailscale` container and not that of the Docker host. Integrations that discover devices in your local network by broadcast may therefore not find them. -If you encounter a `400: Bad Request` after deployment, please alter the file `ha-data/config/configurations.yaml` to trust the reverse proxy configuration used by Tailscale. The `configurations.yaml` should look like this. +## First run -```plain -$ cat ha-data/config/configuration.yaml +1. Start the stack once. Home Assistant creates its configuration in `./home-assistant-data/config`. +2. Home Assistant rejects requests through a reverse proxy that it does not know, and answers `400: Bad Request`. Add this block to `./home-assistant-data/config/configuration.yaml` to trust Tailscale Serve: -# Loads default set of integrations. Do not remove. -default_config: + ```yaml + http: + use_x_forwarded_for: true + trusted_proxies: + - 127.0.0.1 + ``` -# Load frontend themes from the themes folder -frontend: - themes: !include_dir_merge_named themes +3. Restart the stack with `docker compose restart application`. +4. Open the web interface and follow the onboarding. You create the owner account and set your location. -automation: !include automations.yaml -script: !include scripts.yaml -scene: !include scenes.yaml +## Links -http: - use_x_forwarded_for: true - trusted_proxies: - - 127.0.0.1 -``` +- [Home Assistant documentation](https://www.home-assistant.io/docs/) +- [Home Assistant HTTP integration](https://www.home-assistant.io/integrations/http/), for the reverse proxy settings +- [Home Assistant source code](https://github.com/home-assistant/core) diff --git a/services/homebox/README.md b/services/homebox/README.md index 387ca0fe..c305e2cb 100644 --- a/services/homebox/README.md +++ b/services/homebox/README.md @@ -1,62 +1,38 @@ -# Homebox with Tailscale Sidecar Configuration +# Homebox -This Docker Compose configuration sets up **Homebox** with a Tailscale sidecar container, enabling secure access to your self-hosted inventory and asset management system over your private Tailscale network. With this setup, your Homebox instance remains **private and accessible only from authorized devices on your Tailnet**, keeping inventory data and asset metadata protected from public exposure. +[Homebox](https://homebox.software/) is an inventory for your home. You record your items with their location, quantity, warranty, and purchase details. -## Homebox +This stack runs Homebox with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[**Homebox**](https://github.com/sysadminsmedia/homebox) is an open-source, self-hosted home inventory and asset management application developed by SysAdmins Media. It allows you to catalog items, assign them to locations, track quantities, warranties, purchase details, and custom metadata through a clean and intuitive web interface. +## At a glance -Homebox is well suited for homelabs, workshops, offices, and households that want a lightweight but structured way to manage physical assets without relying on third-party SaaS platforms. +| Item | Value | +| ------------- | ---------------------------------- | +| Web interface | `https://homebox..ts.net` | +| Service port | `7745` | +| Image | `ghcr.io/sysadminsmedia/homebox` | +| Data | `./homebox-data` | -## Key Features +## Before you start -- 📦 **Item Inventory** – Track items with names, descriptions, quantities, and images -- 📍 **Location Management** – Organize assets by rooms, racks, shelves, or custom locations -- 🏷️ **Custom Fields & Metadata** – Extend items with your own structured data -- 🧾 **Warranty & Purchase Tracking** – Store purchase dates, vendors, and warranty details -- 🔍 **Search & Filtering** – Quickly find items across large inventories -- 👥 **Multi-User Support** – Share access with trusted users -- 🐳 **Docker-Friendly** – Designed for containerized deployments -- 📦 **Open Source** – Fully self-hosted with no external dependencies +1. Create the data folder yourself and make user `65532` its owner. Docker creates missing folders as user `root`. The stack runs Homebox as user and group `65532`, which cannot write to a folder that `root` owns. -## Why Self-Host? + ```bash + mkdir -p homebox-data + sudo chown 65532:65532 homebox-data + ``` -Inventory and asset data often reflects **physical security, infrastructure layout, and ownership details**. Self-hosting Homebox ensures full control over this information, eliminates dependency on cloud services, and allows deployment in restricted or offline environments. +2. Set `HBOX_AUTH_API_KEY_PEPPER` in `.env` to a random value of at least 32 bytes. Generate one with `openssl rand -base64 48`. Compose stops with an error if it is empty. If you change the value later, all issued API keys become invalid. -When combined with Tailscale, Homebox becomes a **secure, Tailnet-only inventory system** that is reachable from anywhere you need it, without exposing ports or services to the public internet. +## Deviations from the standard setup -## Configuration Overview +- **Fixed user.** The `application` container runs as user and group `65532` through the `user` setting. -In this deployment, a **Tailscale sidecar container** (for example `tailscale-homebox`) runs the Tailscale client and joins your private Tailscale network. The main `homebox` service uses: +## First run -```plain -network_mode: service:tailscale -``` +Open the web interface and register the first account. -This configuration routes all inbound and outbound traffic through the Tailscale interface, ensuring that the Homebox web UI and API are accessible **only via your Tailscale network**. No public port exposure is required unless explicitly configured. +## Links -Homebox listens internally on port **7745**, which is the port that should be referenced if Tailscale Serve is enabled. - -## Volume Permissions - -Homebox stores all persistent data under `/data` inside the container. When using bind mounts, the host directory **must be pre-created with the correct ownership**, otherwise Docker will create it as `root:root`, which will cause permission issues when running the container as a non-root user. - -Before starting the stack, ensure the data directory is owned by UID/GID `65532`: - -```plain -chown 65532:65532 homebox-data/ -``` - -This is especially important when using the rootless or hardened Homebox images and when running the service with: - -```plain -user: 65532:65532 -``` - -## Files to check - -Please check the following contents for validity as some variables need to be defined upfront. - -- `.env` - - Required: `TS_AUTHKEY` - - Required: `HBOX_AUTH_API_KEY_PEPPER`, at least 32 bytes. Generate it with `openssl rand -base64 48`. Compose stops with an error if it is empty. Changing it later invalidates all issued API keys. +- [Homebox documentation](https://homebox.software/en/) +- [Homebox source code](https://github.com/sysadminsmedia/homebox) diff --git a/services/homepage/README.md b/services/homepage/README.md index c1b93a30..319a538b 100644 --- a/services/homepage/README.md +++ b/services/homepage/README.md @@ -1,11 +1,32 @@ -# Homepage with Tailscale Sidecar Configuration +# Homepage -This Docker Compose configuration sets up [Homepage](https://github.com/gethomepage/homepage) with Tailscale as a sidecar container to securely access your personal dashboard over a private Tailscale network. By using Tailscale in a sidecar configuration, you can enhance the security and privacy of your Homepage instance, ensuring that it is only accessible within your Tailscale network. +[Homepage](https://gethomepage.dev/) is a dashboard for your services and bookmarks. It shows live information from many applications and from Docker. -## Homepage +This stack runs Homepage with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Homepage](https://github.com/gethomepage/homepage) is a modern, customizable, and self-hosted dashboard for organizing and accessing your personal services and information. It integrates with a variety of applications and APIs to display real-time stats, service health, and links in one central interface. This configuration leverages Tailscale to securely connect to your Homepage dashboard, ensuring that your self-hosted interface is protected from unauthorized access and only reachable via your private Tailscale network. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | ----------------------------------- | +| Web interface | `https://homepage..ts.net` | +| Service port | `3000` | +| Image | `ghcr.io/gethomepage/homepage` | +| Data | `./homepage-data/config` | -In this setup, the `tailscale-homepage` service runs Tailscale, which manages secure networking for the Homepage service. The `homepage` service uses the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This setup ensures that Homepage’s web interface is only accessible through the Tailscale network (or locally, if preferred), providing an extra layer of security and privacy for your self-hosted dashboard. +## Before you start + +Set `TAILNET_NAME` in `.env` to your Tailnet name, without `.ts.net`. Homepage only answers requests for the host name in `HOMEPAGE_ALLOWED_HOSTS`, which `compose.yaml` builds as `homepage..ts.net`. + +## Deviations from the standard setup + +- **Allowed host.** `HOMEPAGE_ALLOWED_HOSTS` contains the fixed name `homepage`. If you change `SERVICE` in `.env`, change this value in `compose.yaml` as well. +- **Docker socket.** Homepage mounts `/var/run/docker.sock` read-only for its Docker integration. Remove the line if you do not use it. + +## First run + +Homepage has no login. Open the web interface, then edit the YAML files in `./homepage-data/config` to add your services, bookmarks, and widgets. + +## Links + +- [Homepage documentation](https://gethomepage.dev/configs/) +- [Homepage source code](https://github.com/gethomepage/homepage) diff --git a/services/hytale/README.md b/services/hytale/README.md index 6ca32911..4340dc49 100644 --- a/services/hytale/README.md +++ b/services/hytale/README.md @@ -1,26 +1,41 @@ -# Hytale Server with Tailscale Sidecar Configuration +# Hytale Server -This Docker Compose configuration sets up a Hytale game server with Tailscale as a sidecar container to place the server directly on your Tailnet. The Hytale container uses the Tailscale network stack via `network_mode: service:tailscale`, so players connect over Tailscale without exposing the UDP port publicly. +This stack runs a [Hytale](https://hytale.com/) game server with the community image [`deinfreu/hytale-server`](https://deinfreu.github.io/hytale-server-container/installation/container_installation/). Players connect to it over your Tailnet. -## Hytale Server +This stack runs Hytale Server with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -The Hytale server runs from `deinfreu/hytale-server:experimental` and is configured for UDP port `5520`. The game server data is stored in the `${SERVICE}-data` directory to persist across restarts. +## At a glance -Upstream container details and install notes: -[https://deinfreu.github.io/hytale-server-container/installation/container_installation/](https://deinfreu.github.io/hytale-server-container/installation/container_installation/) +| Item | Value | +| ------------- | ------------------------------------------------------- | +| Web interface | None | +| Game server | `hytale..ts.net`, UDP port `5520` | +| Image | `deinfreu/hytale-server:experimental` | +| Data | `./hytale-data` (game files, worlds, and configuration) | -## Key Notes +## Before you start -* First-time authentication should be done attached (do not use `-d` initially). -* Game files, world data, and configuration are stored in the data volume and persist across restarts. +Nothing beyond the [Quick Start](../../README.md#quick-start). -## Configuration Overview +## Deviations from the standard setup -In this setup, the `tailscale` service runs the Tailscale client to join your private mesh network. The `application` service is configured with `network_mode: service:tailscale`, so all network traffic for the game server is routed through the Tailscale container. The sidecar binds UDP `5520` for Tailnet access only. +- **No Tailscale Serve.** The game uses UDP, which Tailscale Serve does not forward. The server listens on UDP port `5520` of the Tailscale IP address of the device, and the stack has no Serve configuration. +- **Machine ID.** The stack mounts `/etc/machine-id` of the Docker host read-only. +- **Interactive console.** The `application` container has `tty` and `stdin_open` enabled, so that you can attach to the server console. +- **Server settings.** `SERVER_IP`, `SERVER_PORT`, `PROD`, and `DEBUG` in `.env` are passed to the server. -## Files to check +## First run -Please verify the following files and variables before deploying: +1. Start the stack in the foreground the first time, without `-d`, because the server asks you to authenticate: -* `.env` — define `SERVICE`, `IMAGE_URL`, `SERVICEPORT`, `TS_AUTHKEY`, and the Hytale variables (`SERVER_IP`, `SERVER_PORT`, `PROD`, `DEBUG`, `TZ`). -* `compose.yaml` — confirm environment variables and volume mappings for your server. + ```bash + docker compose up + ``` + +2. Follow the authentication steps that the server prints. See the [installation notes of the image](https://deinfreu.github.io/hytale-server-container/installation/container_installation/). +3. Stop the stack with `Ctrl+C` and start it in the background with `docker compose up -d`. +4. In the game, connect to `hytale..ts.net`. All players must be on your Tailnet, or you must share the device with them. + +## Links + +- [Hytale server container documentation](https://deinfreu.github.io/hytale-server-container/installation/container_installation/) diff --git a/services/immich/README.md b/services/immich/README.md index 82258116..55c78f2e 100644 --- a/services/immich/README.md +++ b/services/immich/README.md @@ -1,31 +1,66 @@ -# Immich with Tailscale Sidecar Configuration +# Immich -This Docker Compose configuration sets up Immich with Tailscale as a sidecar container, enabling secure access to your photo and video library from anywhere on your private Tailscale network. With this setup, your Immich instance remains completely private and protected, accessible only to your authorized devices. +[Immich](https://immich.app/) is a self-hosted photo and video library. It backs up the media from your mobile devices and lets you browse, search, and share it. -**Please note** Immich changes the [docker-compose](https://immich.app/docs/install/docker-compose) often, we try to match the docker-compose in this repo to theirs, but make sure to check for yourself. +This stack runs Immich with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -## Immich +## At a glance -Immich is a self-hosted, high-performance solution for backing up and browsing photos and videos from your mobile devices. It offers a sleek interface, automatic uploads, facial recognition, albums, search, and metadata support—all while keeping your media under your control. Immich is a privacy-first alternative to commercial cloud-based photo services, ideal for individuals or families. +| Item | Value | +| ------------- | ------------------------------------------------------------- | +| Web interface | `https://immich..ts.net` | +| Service port | `2283` | +| Images | `ghcr.io/immich-app/immich-server` | +| | `ghcr.io/immich-app/immich-machine-learning` | +| | `docker.io/valkey/valkey` | +| | `ghcr.io/immich-app/postgres` | +| Data | `./immich-data/upload` (photos and videos) | +| | `./immich-data/database` (Postgres database) | +| | `./immich-data/model-cache` (machine learning models) | -## Key Features +## Before you start -* **Automatic Uploads** – Sync photos and videos from mobile devices instantly. -* **Albums & Timeline** – Organize and view media in an intuitive gallery. -* **Face Recognition & Object Detection** – Smart tools to tag and sort images. -* **Multi-User Support** – Share with family while maintaining user boundaries. -* **Self-Hosted** – Run on your own server with full control. -* **Private by Default with Tailscale** – Secured with Tailscale, accessible only to you. +* **Set a database password.** Change `DB_PASSWORD` in `.env` to a random value. Use only the characters `A-Za-z0-9`. +* **Choose where your media is stored.** To keep your photos and videos on another disk, set `UPLOAD_LOCATION` before the first start. See [Storage locations](#storage-locations). +* **Compare with upstream.** Immich changes its [Compose file](https://docs.immich.app/install/docker-compose) often. We try to keep this stack in line with it, but check for yourself before you deploy. -## Configuration Overview +## Deviations from the standard setup -In this deployment, the `tailscale-immich` service runs the Tailscale client to establish a secure private network. The `immich` container uses `network_mode: service:tailscale` to route its traffic through the Tailscale interface. This ensures that the Immich web UI and backend services are only reachable via your Tailscale network, keeping your personal media safe from public exposure. +* **Extra containers.** Besides `application`, the stack runs `immich-machine-learning`, `redis` (Valkey), and `database` (Postgres). These three use the default Compose network and not the network of the `tailscale` container. Immich reaches them by their service name through Docker's DNS. +* **Images are set in `compose.yaml`.** The stack does not use `IMAGE_URL`. `IMMICH_VERSION` in `.env` selects the version of the server and machine learning images. +* **Keep `TS_ACCEPT_DNS` disabled.** The `application` service shares the DNS configuration of the `tailscale` service. With `TS_ACCEPT_DNS=true`, Tailscale replaces Docker's DNS with MagicDNS, which cannot resolve the `database`, `redis`, and `immich-machine-learning` services. Immich then fails to start with `getaddrinfo ENOTFOUND database`. You can reach Immich over your Tailnet without this setting. +* **The containers read the whole `.env` file.** As in the upstream Compose file, the Immich containers load `.env` through `env_file`. Every variable in that file, including `TS_AUTHKEY`, is therefore present in the environment of the `application` and `immich-machine-learning` containers. -## Usage Notes +## First run -* **Keep `TS_ACCEPT_DNS` disabled.** The `application` service shares the DNS configuration of the `tailscale` service. With `TS_ACCEPT_DNS=true`, Tailscale replaces Docker's DNS with MagicDNS, which cannot resolve the `database`, `redis`, and `immich-machine-learning` services. Immich then fails to start with `getaddrinfo ENOTFOUND database`. You can reach Immich over your Tailnet without this setting. -* **Resolving MagicDNS names from Immich.** If Immich itself must look up other Tailnet devices by name, such as an OAuth provider or SMTP server, uncomment the `dns` block of the `tailscale` service and set `100.100.100.100` as the DNS server. Docker keeps resolving the service names and forwards all other lookups to MagicDNS. Use the full name, such as `device.example.ts.net`. -* **Remote machine learning.** If you run the machine learning container on another Tailnet device, your Tailnet policy must allow the Immich node to reach that device on TCP port `3003`. Otherwise the `tailscale` service logs `rejected due to acl`. A grant from the Immich node to the machine learning host with `"ip": ["tcp:3003"]` is enough. Keep `TS_USERSPACE=false`, because Immich must open connections to the Tailnet. Use the host's Tailscale IP address in the machine learning URL, or its MagicDNS name with the `dns` block described above. -* **Storage locations.** `UPLOAD_LOCATION` and `DB_DATA_LOCATION` in `.env` set where Immich stores your media and its database. The defaults are `./immich-data/upload` and `./immich-data/database`. To move your media to another disk, set `UPLOAD_LOCATION` to an absolute path. Keep the database on a local disk, because Immich does not support network shares for it. -* **Updating an existing installation.** Earlier versions of this stack ignored both variables and always used the default folders. If your `.env` still contains `UPLOAD_LOCATION=./library` or `DB_DATA_LOCATION=./postgres`, replace them with the defaults above before you restart. Otherwise Immich starts with an empty library and a new database. Your existing files stay untouched in `./immich-data`. -* **Renamed services.** Immich connects to the hostnames `database` and `redis` by default. If you rename these services in `compose.yaml`, set `DB_HOSTNAME` and `REDIS_HOSTNAME` in `.env` to the new names. +Open the web interface and select **Getting Started**. The first user to register becomes the administrator and can add other users. + +In the Immich mobile app, use `https://immich..ts.net` as the server address. The device must be connected to your Tailnet. + +## Configuration + +### Storage locations + +`UPLOAD_LOCATION` and `DB_DATA_LOCATION` in `.env` set where Immich stores your media and its database. The defaults are `./immich-data/upload` and `./immich-data/database`. To move your media to another disk, set `UPLOAD_LOCATION` to an absolute path. Keep the database on a local disk, because Immich does not support network shares for it. + +### MagicDNS names + +If Immich itself must look up other Tailnet devices by name, such as an OAuth provider or SMTP server, uncomment the `dns` block of the `tailscale` service and set `100.100.100.100` as the DNS server. Docker keeps resolving the service names and forwards all other lookups to MagicDNS. Use the full name, such as `device.example.ts.net`. + +### Remote machine learning + +If you run the machine learning container on another Tailnet device, your Tailnet policy must allow the Immich node to reach that device on TCP port `3003`. Otherwise the `tailscale` service logs `rejected due to acl`. A grant from the Immich node to the machine learning host with `"ip": ["tcp:3003"]` is enough. Keep `TS_USERSPACE=false`, because Immich must open connections to the Tailnet. Use the host's Tailscale IP address in the machine learning URL, or its MagicDNS name with the `dns` block described above. + +### Renamed services + +Immich connects to the hostnames `database` and `redis` by default. If you rename these services in `compose.yaml`, set `DB_HOSTNAME` and `REDIS_HOSTNAME` in `.env` to the new names. + +## Upgrading + +Earlier versions of this stack ignored `UPLOAD_LOCATION` and `DB_DATA_LOCATION` and always used the default folders. If your `.env` still contains `UPLOAD_LOCATION=./library` or `DB_DATA_LOCATION=./postgres`, replace them with the defaults from [Storage locations](#storage-locations) before you restart. Otherwise Immich starts with an empty library and a new database. Your existing files stay untouched in `./immich-data`. + +## Links + +* [Immich documentation](https://docs.immich.app/) +* [Immich environment variables](https://docs.immich.app/install/environment-variables) +* [Immich source code](https://github.com/immich-app/immich) diff --git a/services/isley/README.md b/services/isley/README.md index a3d650ea..c5965e72 100644 --- a/services/isley/README.md +++ b/services/isley/README.md @@ -1,27 +1,31 @@ -# Isley with Tailscale Sidecar Configuration +# Isley -This Docker Compose configuration sets up [Isley](https://github.com/dwot/isley) with Tailscale as a sidecar container, enabling secure and private access to your self-hosted cannabis grow journal over a Tailscale network. With Tailscale, you can ensure that your sensitive grow data and notes are only accessible by trusted devices within your Tailnet. +[Isley](https://github.com/dwot/isley) is a grow journal for home growers. You log your plants, watering, and feeding, follow sensor data from your grow equipment, and keep track of seeds and harvests. -## Isley +This stack runs Isley with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Isley](https://github.com/dwot/isley) is a self-hosted cannabis grow journal designed for home growers to track and monitor their plants with ease. It replaces vendor apps, spreadsheets, and notepads by centralizing tools into a clean, intuitive interface. Isley helps growers with some Key Features 🚀 +## At a glance -- **📒 Grow Logs**: Track plant growth, watering, and feeding schedules. -- **🌡️ Environmental Monitoring**: View real-time data from grow equipment (AC Infinity, Ecowitt). -- **📸 Image Uploads**: Attach photos to your grow logs for visual tracking. -- **🌱 Seed Inventory**: Manage your seed collection and strain library. -- **📊 Harvest Tracking**: Record harvest details and yields. -- **📈 Graphs and Charts**: Visualize environmental data and plant progress over time. -- **⚙️ Customizable Settings**: Add custom activities and measurements for your grow. -- **📱 Mobile-Friendly**: Works on desktop and mobile devices for convenience. +| Item | Value | +| ------------- | ---------------------------------------------- | +| Web interface | `https://isley..ts.net` | +| Service port | `8080` | +| Image | `dwot/isley` | +| Data | `./isley-data/isley-db` (database) | +| | `./isley-data/isley-uploads` (uploaded images) | -With integration options for popular grow equipment, Isley simplifies and elevates the grow experience by consolidating everything into one powerful and private tool. +## Before you start -## Default Credentials +Nothing beyond the [Quick Start](../../README.md#quick-start). -- **Default Username:** `admin` -- **Default Password:** `isley` +## Deviations from the standard setup -## Configuration Overview +None. -In this setup, the `tailscale-isley` service runs Tailscale, which manages secure networking for the Isley service. The `isley` service uses the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This ensures that Isley's interface is not exposed to the public internet, protecting your grow journal and data with an additional layer of privacy. +## First run + +Open the web interface and log in with username `admin` and password `isley`. Isley then asks you to set a new password. + +## Links + +- [Isley documentation and source code](https://github.com/dwot/isley) diff --git a/services/it-tools/README.md b/services/it-tools/README.md index 7c3999c5..9f347062 100644 --- a/services/it-tools/README.md +++ b/services/it-tools/README.md @@ -1,11 +1,30 @@ -# IT-Tools with Tailscale Sidecar Configuration +# IT-Tools -This Docker Compose configuration sets up [IT-Tools](https://github.com/CorentinTh/it-tools) with Tailscale as a sidecar container to securely access your all-in-one developer utility over a private Tailscale network. By using Tailscale in a sidecar configuration, you can enhance the security and privacy of your IT-Tools instance, ensuring that it is only accessible within your Tailscale network. +[IT-Tools](https://github.com/CorentinTh/it-tools) is a collection of tools for developers and IT staff, such as converters, encoders, formatters, and generators. -## IT-Tools +This stack runs IT-Tools with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[IT-Tools](https://github.com/CorentinTh/it-tools) is an open-source collection of online utilities designed for developers and IT professionals. It includes a variety of tools such as encoders, converters, formatters, and more—all in one sleek, web-based application. This configuration leverages Tailscale to securely connect to your IT-Tools instance, ensuring that your suite of developer utilities is protected from unauthorized access and accessible only via your private Tailscale network. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | ----------------------------------- | +| Web interface | `https://it-tools..ts.net` | +| Service port | `80` | +| Image | `corentinth/it-tools` | +| Data | None | -In this setup, the `tailscale-it-tools` service runs Tailscale, which manages secure networking for the IT-Tools service. The `it-tools` service uses the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This setup ensures that IT-Tools’ web interface is only accessible through the Tailscale network (or locally, if preferred), providing an extra layer of security and privacy for your self-hosted developer utilities. +## Before you start + +Nothing beyond the [Quick Start](../../README.md#quick-start). + +## Deviations from the standard setup + +- **No data folder.** IT-Tools runs in your browser and stores nothing on the server, so the stack has no volumes. + +## First run + +Nothing to set up. Open the web interface. + +## Links + +- [IT-Tools source code](https://github.com/CorentinTh/it-tools) diff --git a/services/jellyfin/README.md b/services/jellyfin/README.md index 1547ac48..abb352be 100644 --- a/services/jellyfin/README.md +++ b/services/jellyfin/README.md @@ -1,11 +1,36 @@ -# Jellyfin with Tailscale Sidecar Configuration +# Jellyfin -This Docker Compose configuration sets up [Jellyfin](https://github.com/jellyfin/jellyfin) with Tailscale as a sidecar container to securely manage and access your media server over a private Tailscale network. By using Tailscale in a sidecar configuration, you can enhance the security and privacy of your Jellyfin instance, ensuring that it is only accessible within your Tailscale network. +[Jellyfin](https://jellyfin.org/) is a media server. It organises your movies, series, and music and streams them to your browser, television, and mobile devices. -## Jellyfin +This stack runs Jellyfin with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Jellyfin](https://github.com/jellyfin/jellyfin) is an open-source, self-hosted media server that allows you to manage and stream your media collection, including movies, TV shows, music, and more, to various devices. It provides a rich user interface and supports multiple clients, making it a powerful alternative to other media server solutions. This configuration leverages Tailscale to securely connect to your Jellyfin instance, ensuring that your media server interface is protected from unauthorized access and that your instance is accessible only via your private Tailscale network. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | ------------------------------------------------------------- | +| Web interface | `https://jellyfin..ts.net` | +| Service port | `8096` | +| Image | `lscr.io/linuxserver/jellyfin` | +| Data | `./jellyfin-data/config` (configuration, database, and cache) | +| | `./media/movies` (movie library) | +| | `./media/tvseries` (series library) | -In this setup, the tailscale-jellyfin service runs Tailscale, which manages secure networking for the Jellyfin service. The jellyfin service uses the Tailscale network stack via Docker's network_mode: service:tailscale configuration. This setup ensures that Jellyfin’s web interface and API are only accessible through the Tailscale network (or locally, if preferred), providing an extra layer of security and privacy for your self-hosted media server. +## Before you start + +Point the `/data/movies` and `/data/tvshows` volumes in `compose.yaml` at your own media folders. Otherwise the stack starts with empty folders in `./media`. + +## Deviations from the standard setup + +- **Media folders.** The libraries are in `./media`, outside the `./jellyfin-data` folder. + +## First run + +Open the web interface. The setup wizard asks for the display language, the administrator account, your media libraries, and the metadata language. Use `/data/movies` and `/data/tvshows` as the library folders. + +In the Jellyfin apps, use `https://jellyfin..ts.net` as the server address. The device must be connected to your Tailnet. + +## Links + +- [Jellyfin documentation](https://jellyfin.org/docs/) +- [Jellyfin source code](https://github.com/jellyfin/jellyfin) +- [LinuxServer.io image documentation](https://docs.linuxserver.io/images/docker-jellyfin/) diff --git a/services/kaneo/README.md b/services/kaneo/README.md index 82ce868c..cdff3178 100644 --- a/services/kaneo/README.md +++ b/services/kaneo/README.md @@ -1,19 +1,40 @@ -# Kaneo with Tailscale Sidecar Configuration +# Kaneo -This Docker Compose configuration sets up **[Kaneo](https://github.com/usekaneo/kaneo)** with Tailscale as a sidecar container to securely manage and access your self-hosted project management platform over a private Tailscale network. By integrating Tailscale, you ensure that your Kaneo instance is only accessible to authorized devices within your Tailscale network, keeping your tasks, projects, and team discussions private. +[Kaneo](https://kaneo.app/) is a project management tool with boards, tasks, and a clean interface. It is an open-source alternative to tools such as Trello and Linear. -## Kaneo +This stack runs Kaneo with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Kaneo](https://github.com/usekaneo/kaneo) is an **open-source, self-hosted project management platform** focused on simplicity, clean UI, and efficient workflows. Designed as an alternative to tools like Trello or Linear, Kaneo offers a modern and distraction-free environment to manage tasks, organize projects, and collaborate with your team. You can self-host and fully customize the platform to match your workflow—no vendor lock-in, no subscriptions. +## At a glance -## Key Features +| Item | Value | +| ------------- | -------------------------------------------------- | +| Web interface | `https://kaneo..ts.net` | +| Service ports | `5173` (web interface) and `1337` (API) | +| Images | `ghcr.io/usekaneo/web` | +| | `ghcr.io/usekaneo/api` | +| | `postgres:16-alpine` | +| Data | `./kaneo-data/postgres_data` (PostgreSQL database) | -- **Project & Task Boards** – Kanban-style boards for managing tasks and workflows. -- **Clean & Fast UI** – Minimalist design focused on usability and speed. -- **Self-Hosted & Customizable** – Deploy on your own infrastructure and modify freely. -- **Privacy-First** – No tracking, no external dependencies. -- **Secure Access with Tailscale** – Limit access to authorized devices in your private network. +## Before you start -## Configuration Overview +Set these values in `.env`: -In this setup, the `tailscale-kaneo` service runs Tailscale, which manages secure networking for the Kaneo service. The `kaneo` service uses the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This ensures that Kaneo’s web interface is only accessible through the Tailscale network (or locally, if preferred), adding a strong layer of privacy and security to your self-hosted project management platform. +- **`KANEO_CLIENT_URL` and `KANEO_API_URL`.** The address of the web interface, `https://kaneo..ts.net`, and the same address with `/api`. The backend does not start with the sample values. +- **`AUTH_SECRET`.** A long random value, for example from `openssl rand -hex 32`. +- **`DB_PASSWORD`.** The password of the database. + +## Deviations from the standard setup + +- **Three application containers.** The stack has no `application` service. It runs `frontend`, `backend`, and `postgres`, which all use the network of the `tailscale` container and reach each other at `localhost`. PostgreSQL therefore also listens on port `5432` of the Tailscale IP address of the device. +- **Two Serve routes.** Tailscale Serve forwards `/api/` to the backend and everything else to the frontend. The ports come from `SERVICEPORT_BACKEND` and `SERVICEPORT_FRONTEND` in `.env`. +- **Images are set in `.env`.** The stack does not use `IMAGE_URL` and `SERVICEPORT`. `IMAGE_URL_FRONTEND`, `IMAGE_URL_BACKEND`, and `IMAGE_URL_DATABASE` select the images. +- **The containers read the whole `.env` file.** All three containers load `.env` through `env_file`. Every variable in that file, including `TS_AUTHKEY`, is therefore present in their environment. + +## First run + +Open the web interface and sign up to create the first account. Then create your workspace. + +## Links + +- [Kaneo documentation](https://kaneo.app/docs) +- [Kaneo source code](https://github.com/usekaneo/kaneo) diff --git a/services/karakeep/README.md b/services/karakeep/README.md index 614d4bbe..2547761d 100644 --- a/services/karakeep/README.md +++ b/services/karakeep/README.md @@ -1,37 +1,40 @@ -# Karakeep with Tailscale Sidecar Configuration - -This Docker Compose configuration sets up **[Karakeep](https://github.com/karakeep-app/karakeep)** with Tailscale as a sidecar container to securely manage and access your self-hosted notes and collaboration app over a private Tailscale network. By integrating Tailscale, you can ensure that your Karakeep instance is only accessible to authorized devices within your Tailscale network, protecting your ideas and information from the public web. - -## Karakeep - -[Karakeep](https://github.com/karakeep-app/karakeep) is an open-source, self-hosted **bookmark-everything app (links, notes and images)** with AI-based automatic tagging and full text search. - -## Key Features - -- 🔗 Bookmark links, take simple notes and store images and pdfs. -- ⬇️ Automatic fetching for link titles, descriptions and images. -- 📋 Sort your bookmarks into lists. -- 👥 Collaborate with others on the same list. -- 🔎 Full text search of all the content stored. -- ✨ AI-based (aka chatgpt) automatic tagging and summarization. With supports for local models using ollama! -- 🤖 Rule-based engine for customized management. -- 🎆 OCR for extracting text from images. -- 🔖 Chrome plugin and Firefox addon for quick bookmarking. -- 📱 An iOS app, and an Android app. -- 📰 Auto hoarding from RSS feeds. -- 🔌 REST API and multiple clients. -- 🌐 Multi-language support. -- 🖍️ Mark and store highlights from your hoarded content. -- 🗄️ Full page archival (using monolith) to protect against link rot. -- ▶️ Auto video archiving using yt-dlp. -- ☑️ Bulk actions support. -- 🔐 SSO support. -- 🌙 Dark mode support. -- 💾 Self-hosting first. Own your data, free from third-party cloud services. -- ⬇️ Bookmark importers from Chrome, Pocket, Linkwarden, Omnivore, Tab Session Manager. -- 🔄 Automatic sync with browser bookmarks via floccus. -- **Secure Access with Tailscale** – Restrict access to your data using your private Tailscale network. - -## Configuration Overview - -In this setup, the `tailscale-karakeep` service runs Tailscale, which manages secure networking for the Karakeep service. The `karakeep` service uses the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This ensures that Karakeep’s web interface is only accessible through the Tailscale network (or locally, if preferred), enhancing the privacy and security of your notes and collaborative workspace. +# Karakeep + +[Karakeep](https://karakeep.app/) is a bookmark manager for links, notes, and images. It archives the pages that you save, searches their full text, and can tag them automatically with AI. + +This stack runs Karakeep with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). + +## At a glance + +| Item | Value | +| ------------- | -------------------------------------------------------- | +| Web interface | `https://karakeep..ts.net` | +| Service port | `3000` | +| Images | `ghcr.io/karakeep-app/karakeep` | +| | `ghcr.io/karakeep-app/karakeep-chrome:release` | +| | `getmeili/meilisearch:v1.11.1` | +| Data | `./karakeep-data/data` (bookmarks, assets, and database) | +| | `./karakeep-data/meilisearch` (search index) | + +## Before you start + +Set these values in `.env`: + +- **`NEXTAUTH_URL`.** The address of the web interface, `https://karakeep..ts.net`. Karakeep does not start with the sample value. +- **`NEXTAUTH_SECRET` and `MEILI_MASTER_KEY`.** Two different random values, for example from `openssl rand -base64 36`. The sample values are public. + +## Deviations from the standard setup + +- **Service name.** The application service is called `web`, not `application`, and its container is `app-karakeep-web`. +- **Extra containers.** The stack runs `chrome`, a headless browser that fetches the pages, and `meilisearch` for the search. They use the default Compose network, and Karakeep reaches them by their service name through Docker's DNS. Keep `TS_ACCEPT_DNS` disabled, because MagicDNS cannot resolve these names. +- **Images are set in `compose.yaml`.** The stack does not use `IMAGE_URL`. `KARAKEEP_VERSION` in `.env` selects the version of the Karakeep image. +- **The containers read the whole `.env` file.** The `web` and `meilisearch` containers load `.env` through `env_file`. Every variable in that file, including `TS_AUTHKEY`, is therefore present in their environment. + +## First run + +Open the web interface and sign up. The first account becomes the administrator. To stop others from registering afterwards, set `DISABLE_SIGNUPS=true` in `.env` and restart the stack. + +## Links + +- [Karakeep documentation](https://docs.karakeep.app/) +- [Karakeep source code](https://github.com/karakeep-app/karakeep) diff --git a/services/kavita/README.md b/services/kavita/README.md index 869abc89..feb5e63b 100644 --- a/services/kavita/README.md +++ b/services/kavita/README.md @@ -1,28 +1,32 @@ -# Kavita with Tailscale Sidecar Configuration +# Kavita -This Docker Compose configuration sets up [Kavita](https://github.com/Kareadita/Kavita) with Tailscale as a sidecar container to securely serve your comics, manga, and ebooks over a private Tailscale network. By running Tailscale as a sidecar, you restrict access to your Kavita instance to devices authenticated on your Tailnet, avoiding public exposure. +[Kavita](https://www.kavitareader.com/) is a digital library for comics, manga, and books. You read in the browser, and Kavita keeps your reading progress in sync between your devices. -## Kavita +This stack runs Kavita with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Kavita](https://github.com/Kareadita/Kavita) is an open-source, self-hosted digital library manager optimized for comics, manga, and ebooks. It provides a modern web UI for browsing collections, reading in-browser, managing metadata, and syncing reading progress across devices. Kavita supports multiple users, libraries, and common archive formats. +## At a glance -## Key Features +| Item | Value | +| ------------- | ----------------------------------------------------------------------------------------- | +| Web interface | `https://kavita..ts.net` | +| Service port | `5000` | +| Image | `jvmilazz0/kavita` | +| Data | `./kavita-data/config` (configuration and database) | +| | `./kavita-data/manga`, `./kavita-data/comics`, and `./kavita-data/books` (your libraries) | -* **Library Management** – Organize comics, manga, and ebooks with metadata, tags, and collections. -* **In-Browser Reader** – Read content directly in the browser with smooth navigation and zoom controls. -* **Multi-User Support** – Create accounts with individualized reading progress and permissions. -* **Archive Support** – Handles CBZ, CBR, EPUB, and other common formats. -* **Self-Hosted & Private** – Keep your media on your infrastructure. -* **Private by Default with Tailscale** – Access Kavita only from devices on your Tailnet. +## Before you start -## Configuration Overview +To use an existing collection, point the `/manga`, `/comics`, and `/books` volumes in `compose.yaml` at your own folders. Otherwise the stack starts with empty folders in `./kavita-data`. -In this setup, the `tailscale-kavita` service runs the Tailscale client to join your private mesh network. The `kavita` service is configured with `network_mode: service:tailscale`, so all network traffic for Kavita is routed through the Tailscale container. This ensures the web UI and API are reachable only via your Tailscale network (or locally), adding an extra layer of privacy and security to your self-hosted library. +## Deviations from the standard setup -## Files to check +None. -Please verify the following files and variables before deploying: +## First run -* `.env` — define SERVICE, IMAGE_URL, SERVICEPORT, TS_AUTHKEY, etc. -* `./config/serve.json` — optional Tailscale Serve configuration if you want to expose specific ports within the Tailnet. -* `./kavita-data` — ensure persistent volumes for libraries and config are correctly mapped. +Open the web interface and create the administrator account. Then add a library for each of the folders `/manga`, `/comics`, and `/books`. + +## Links + +- [Kavita documentation](https://wiki.kavitareader.com/) +- [Kavita source code](https://github.com/Kareadita/Kavita) diff --git a/services/kitchenowl/README.md b/services/kitchenowl/README.md index 84869ad6..f2aca7c7 100644 --- a/services/kitchenowl/README.md +++ b/services/kitchenowl/README.md @@ -1,58 +1,45 @@ -# Kitchenowl with Tailscale Sidecar Configuration +# KitchenOwl -This Docker Compose configuration sets up **Kitchenowl** with a Tailscale sidecar container, enabling secure, private access to your self-hosted grocery list, recipe manager, and meal planner over your Tailnet. With this setup, your Kitchenowl instance is **not exposed to the public internet** and is only accessible from authorized devices connected via Tailscale. +[KitchenOwl](https://kitchenowl.org/) is a grocery list and recipe manager for households. You share shopping lists, collect recipes, plan your meals, and track expenses together. -## Kitchenowl +This stack runs KitchenOwl with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[**Kitchenowl**](https://github.com/TomBursch/kitchenowl) is a self-hosted grocery list, recipe manager, and meal planning application designed for households and shared kitchens. It helps you organize shopping lists, recipes, weekly meal plans, pantry items, and household food planning from a central web interface. +## At a glance -Kitchenowl is useful for families, housemates, and home labs that want a private alternative to cloud-hosted grocery and recipe apps. It supports collaborative lists, recipe import workflows, meal planning, and optional account integration features, making it a practical tool for day-to-day kitchen organization. +| Item | Value | +| ------------- | ------------------------------------- | +| Web interface | `https://kitchenowl..ts.net` | +| Service port | `8080` | +| Image | `tombursch/kitchenowl` | +| Data | `./kitchenowl-data` | -## Key Features +## Before you start -- 🛒 Shared grocery lists for households and teams -- 🍽️ Recipe management with rich recipe import options -- 📅 Weekly meal planning for organizing upcoming meals -- 💸 Expense tracking for grocery and household food costs -- 🧺 Pantry and household item organization -- 👥 Multi-user collaboration for shared kitchens -- 🔐 Optional OpenID Connect support for external authentication -- 🛡️ Tailnet-only access when paired with the included Tailscale sidecar +Set `JWT_SECRET_KEY` in `.env` to a long random value, for example from `openssl rand -hex 32`. -## Tailscale Integration +## Deviations from the standard setup -This setup uses a **Tailscale sidecar container** to provide secure private networking for Kitchenowl. The Kitchenowl container shares the Tailscale container's network stack using Docker's `network_mode: service:tailscale` pattern. +- **Service name.** The application service is called `kitchenowl`, not `application`. +- **The container reads the whole `.env` file.** The `kitchenowl` container loads `.env` through `env_file`. Every variable in that file, including `TS_AUTHKEY`, is therefore present in its environment. -Because of this, Kitchenowl does not need to publish ports directly to the host. Instead, you access the web interface through the Tailscale hostname or Tailnet IP assigned to the sidecar. This keeps the service private, reduces exposure, and avoids the need for public DNS, inbound firewall rules, or a public reverse proxy. +## First run -## Configuration Overview +Open the web interface and create the first account, which becomes the administrator. Then create your household and invite the other members. -The Compose stack is built around two services: +In the KitchenOwl apps, use `https://kitchenowl..ts.net` as the server address. The device must be connected to your Tailnet. -1. **Tailscale sidecar** - Handles authentication to your Tailnet and provides the private network endpoint for the application. +## Configuration -2. **Kitchenowl application** - Runs the Kitchenowl web interface and uses the Tailscale sidecar's network namespace for secure Tailnet-only access. +### OpenID Connect -Kitchenowl should be configured with persistent storage so recipes, shopping lists, users, pantry data, meal plans, and application settings are retained across container restarts and updates. Review the provided `compose.yaml` and `.env` file before deployment, especially if you want to enable authentication integrations. +KitchenOwl can use an OpenID Connect provider for the login, such as Authentik, Authelia, Keycloak, or [Pocket ID](../pocket-id/). -## OpenID Connect +1. Set `FRONT_URL` in `.env` to the exact address of the web interface, and fill in `OIDC_ISSUER`, `OIDC_CLIENT_ID`, and `OIDC_CLIENT_SECRET`. +2. Uncomment the matching lines in the `environment` block of `compose.yaml`. -Kitchenowl supports OpenID Connect for external authentication providers. This can be useful when integrating Kitchenowl with an existing identity provider such as Authentik, Authelia, Keycloak, or another OIDC-compatible service. +See the [KitchenOwl OpenID Connect documentation](https://docs.kitchenowl.org/latest/self-hosting/oidc/). -To enable OIDC in this ScaleTail service, review the commented OIDC sections in both the `.env` file and the `compose.yaml` file. Uncomment the relevant values and fill in the required provider details before starting the stack. +## Links -You can find the upstream Kitchenowl OIDC documentation here: [Kitchenowl OpenID Connect Documentation](https://docs.kitchenowl.org/latest/self-hosting/oidc/). - -## Usage Notes - -Once logged in, create your household, configure users, and begin adding grocery lists, recipes, pantry items, and meal plans. Since Kitchenowl is designed for shared household use, review user permissions and authentication settings before inviting other people to the instance. - -## References - -- [Kitchenowl Website](https://kitchenowl.org/) -- [Kitchenowl GitHub Repository](https://github.com/TomBursch/kitchenowl) -- [Kitchenowl Documentation](https://docs.kitchenowl.org/) -- [Kitchenowl OpenID Connect Documentation](https://docs.kitchenowl.org/latest/self-hosting/oidc/) -- [Tailscale Docker Documentation](https://tailscale.com/kb/1282/docker) +- [KitchenOwl documentation](https://docs.kitchenowl.org/) +- [KitchenOwl source code](https://github.com/TomBursch/kitchenowl) diff --git a/services/languagetool/README.md b/services/languagetool/README.md index 7d5692a4..cfc9fe80 100644 --- a/services/languagetool/README.md +++ b/services/languagetool/README.md @@ -1,35 +1,62 @@ -# LanguageTool with Tailscale Sidecar Configuration +# LanguageTool -This Docker Compose configuration sets up [LanguageTool](https://languagetool.org) with Tailscale as a sidecar container to enhance secure networking. +[LanguageTool](https://languagetool.org) checks grammar, style, and spelling in many languages. This stack runs its server, which the LanguageTool browser extensions and other clients can use in place of the public service. -## LanguageTool +This stack runs LanguageTool with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[LanguageTool](https://languagetool.org) is a powerful grammar and spell-checking tool available for various languages. It can be used in various applications, including web browsers, office suites, and as a standalone server for integration with other services. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | --------------------------------------------------- | +| Web interface | None | +| API | `https://languagetool..ts.net/v2` | +| Service port | `8010` | +| Image | `erikvl87/languagetool` | +| Data | `./languagetool-data/ngrams` (optional n-gram data) | -In this setup, the `tailscale-adguardhome` service runs Tailscale, which manages secure networking for LanguageTool. The `languagetool` service utilizes the Tailscale network stack via Docker's `network_mode: service:tailscale`. This setup ensures that LanguageTool's service is only accessible through the Tailscale network (or locally, if preferred), providing an extra layer of security and privacy for your LanguageTool deployment. +## Before you start -## Using n-gram datasets +Nothing beyond the [Quick Start](../../README.md#quick-start). -> LanguageTool can make use of large n-gram data sets to detect errors with words that are often confused, like __their__ and __there__. +## Deviations from the standard setup -*Source: [https://dev.languagetool.org/finding-errors-using-n-gram-data](https://dev.languagetool.org/finding-errors-using-n-gram-data)* +- **No web interface.** Tailscale Serve publishes the API of LanguageTool. +- **Memory.** `Java_Xms` and `Java_Xmx` in `compose.yaml` set the Java heap to between 512 MB and 1 GB. -[Download](http://languagetool.org/download/ngram-data/) the n-gram dataset(s) onto your local machine and unzip them into a local ngrams directory: +## First run -```plain -home/ -├─ / -│ ├─ ngrams/ -│ │ ├─ en/ -│ │ │ ├─ 1grams/ -│ │ │ ├─ 2grams/ -│ │ │ ├─ 3grams/ -│ │ ├─ nl/ -│ │ │ ├─ 1grams/ -│ │ │ ├─ 2grams/ -│ │ │ ├─ 3grams/ +Nothing to set up on the server. Test the API from a device on your Tailnet: + +```bash +curl -d "language=en-US" -d "text=This are a test." https://languagetool..ts.net/v2/check ``` -Mount the local ngrams directory to the `/ngrams` directory in the Docker container [using the `-v` configuration](https://docs.docker.com/engine/reference/commandline/container_run/#read-only) and set the `languageModel` configuration to the `/ngrams` folder. +In the LanguageTool browser extension, choose your own server in the advanced settings and enter `https://languagetool..ts.net/v2`. + +## Configuration + +### Use n-gram data + +LanguageTool can use large n-gram data sets to find errors with words that are often confused, such as *their* and *there*. See [Finding errors using n-gram data](https://dev.languagetool.org/finding-errors-using-n-gram-data). + +1. [Download](https://languagetool.org/download/ngram-data/) the data for your languages. +2. Unzip each file into `./languagetool-data/ngrams`, so that each language has its own folder: + + ```text + languagetool-data/ngrams/ + ├─ en/ + │ ├─ 1grams/ + │ ├─ 2grams/ + │ ├─ 3grams/ + ├─ nl/ + │ ├─ 1grams/ + │ ├─ 2grams/ + │ ├─ 3grams/ + ``` + +3. Restart the stack. `compose.yaml` already mounts the folder at `/ngrams` and sets `langtool_languageModel` to it. + +## Links + +- [LanguageTool HTTP API](https://dev.languagetool.org/http-server) +- [erikvl87/languagetool image](https://github.com/Erikvl87/docker-languagetool) diff --git a/services/linkding/README.md b/services/linkding/README.md index 27fbd4e9..f7841b1d 100644 --- a/services/linkding/README.md +++ b/services/linkding/README.md @@ -1,18 +1,40 @@ -# Linkding with Tailscale Sidecar Configuration +# linkding -This Docker Compose configuration sets up [Linkding](https://github.com/sissbruecker/linkding) with Tailscale as a sidecar container to securely manage and access your self-hosted bookmark manager over a private Tailscale network. By integrating Tailscale, you can ensure that your Linkding instance remains private and accessible only to authorized devices on your Tailscale network. +[linkding](https://linkding.link/) is a bookmark manager. You save, tag, and search your links, and a browser extension adds bookmarks with one click. -## Linkding +This stack runs linkding with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Linkding](https://github.com/sissbruecker/linkding) is a lightweight, self-hosted bookmark manager designed to simplify saving and organizing links. It supports features like tagging, searching, and bookmark importing/exporting. It also includes a browser extension for quick access and management. With Tailscale, your Linkding instance is safeguarded, ensuring that your bookmarks are only accessible to you and authorized users within your private network. +## At a glance -## Key Features +| Item | Value | +| ------------- | ----------------------------------- | +| Web interface | `https://linkding..ts.net` | +| Service port | `9090` | +| Image | `sissbruecker/linkding` | +| Data | `./linkding-data/data` | -- **Tagging and Search**: Organize and find bookmarks effortlessly with tags and a robust search feature. -- **Browser Integration**: Quickly save and manage bookmarks via browser extensions. -- **Self-Hosted Privacy**: Keep your bookmarks secure and private with a locally hosted solution. -- **Import/Export**: Easily migrate bookmarks to and from other services. +## Before you start -## Configuration Overview +The settings of linkding are in the file `.linkding.env` in this directory. -In this setup, the `tailscale-linkding` service runs Tailscale, which manages secure networking for the Linkding service. The `linkding` service uses the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This ensures that Linkding’s web interface is only accessible through the Tailscale network (or locally, if preferred), providing enhanced privacy and security for managing your bookmarks. +- **`LD_SUPERUSER_NAME` and `LD_SUPERUSER_PASSWORD`.** Set both to let linkding create your account at the first start. If you leave them empty, create the account by hand after the start, as described under the first run. + +## Deviations from the standard setup + +- **Separate settings file.** The `application` container loads `.linkding.env` through `env_file`, in addition to the variables in `compose.yaml`. + +## First run + +Open the web interface and log in with the account from `.linkding.env`. + +If you did not set an account there, create one first: + +```bash +docker exec -it app-linkding python manage.py createsuperuser --username= --email= +``` + +## Links + +- [linkding documentation](https://linkding.link/) +- [linkding options](https://linkding.link/options/) +- [linkding source code](https://github.com/sissbruecker/linkding) diff --git a/services/lube-logger/README.md b/services/lube-logger/README.md index b9c9a84a..d7daff53 100644 --- a/services/lube-logger/README.md +++ b/services/lube-logger/README.md @@ -1,19 +1,34 @@ -# LubeLogger with Tailscale Sidecar Configuration +# LubeLogger -This Docker Compose configuration sets up **[LubeLogger](https://github.com/hargata/lubelog)** with Tailscale as a sidecar container, enabling secure access to your vehicle maintenance log from anywhere on your private Tailscale network. With this setup, your LubeLogger instance stays completely private and protected, accessible only to your authorized devices. +[LubeLogger](https://lubelogger.com/) tracks the maintenance and fuel use of your vehicles. You log services, repairs, and fill-ups and get reminders for the next ones. -## LubeLogger +This stack runs LubeLogger with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[LubeLogger](https://github.com/hargata/lubelog) is a **self-hosted web app for tracking vehicle maintenance**. Whether you're managing one car or an entire fleet, LubeLogger offers a simple interface to log and monitor oil changes, part replacements, tire rotations, and more. It’s a handy way to maintain service history without relying on third-party platforms or paper logs. +## At a glance -## Key Features +| Item | Value | +| ------------- | -------------------------------------------------------------- | +| Web interface | `https://lubelogger..ts.net` | +| Service port | `8080` | +| Image | `ghcr.io/hargata/lubelogger` | +| Data | `./lubelogger-data/data` (database and documents) | +| | `./lubelogger-data/keys` (keys that protect the login cookies) | -* **Track Maintenance** – Log service events for multiple vehicles. -* **Customizable Entries** – Record any type of maintenance or inspection. -* **Multi-Vehicle Support** – Ideal for families or fleets. -* **Self-Hosted** – Your data, your server. -* **Private by Default with Tailscale** – Runs behind a Tailscale sidecar for private access only. +## Before you start -## Configuration Overview +Set `LUBELOGGER_DOMAIN` in `.env` to the name of the device on your Tailnet, `lubelogger..ts.net`. -In this deployment, the `tailscale-lubelogger` service runs the Tailscale client to establish a secure private network. The `lubelogger` container uses `network_mode: service:tailscale` to tunnel its network traffic through the Tailscale network interface. This ensures that the web UI is accessible only through Tailscale, keeping your vehicle data safe from public exposure. +## Deviations from the standard setup + +- **Device name.** `SERVICE` in `.env` is `lubelogger`, which differs from the name of this directory. +- **The container reads the whole `.env` file.** The `application` container loads `.env` through `env_file`. Every variable in that file, including `TS_AUTHKEY`, is therefore present in its environment. +- **Language settings.** `LC_ALL` and `LANG` in `.env` set the locale, which LubeLogger uses for dates and numbers. + +## First run + +Open the web interface. LubeLogger has no login by default, so everyone who can reach the device on your Tailnet can see and change your data. To require a login, enable authentication in the settings of LubeLogger. + +## Links + +- [LubeLogger documentation](https://docs.lubelogger.com/) +- [LubeLogger source code](https://github.com/hargata/lubelog) diff --git a/services/mailpit/README.md b/services/mailpit/README.md index 0ca69373..33ade185 100644 --- a/services/mailpit/README.md +++ b/services/mailpit/README.md @@ -1,71 +1,62 @@ -# Mailpit with Tailscale Sidecar Configuration +# Mailpit -This Docker Compose configuration sets up [Mailpit](https://mailpit.axllent.org/) with Tailscale as a sidecar container. The Mailpit web interface is available privately over your Tailnet through Tailscale Serve and automatic HTTPS, while SMTP remains publicly reachable on host TCP port `25` so external mail servers can deliver messages. +[Mailpit](https://mailpit.axllent.org/) captures email and shows it in a web interface. It accepts messages over SMTP, stores them locally, and lets you inspect the content, headers, source, and attachments without mailbox accounts. -## Mailpit +This stack accepts mail for every address at one domain, as a catch-all inbox. Mailpit does not send or relay the captured mail. -[Mailpit](https://mailpit.axllent.org/) is a lightweight email capture and inspection tool with a modern web interface. It accepts SMTP messages, stores them locally, and lets you inspect rendered content, headers, raw source, and attachments without requiring individual mailbox accounts. +This stack runs Mailpit with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -This deployment restricts accepted recipients with `MAIL_DOMAIN_REGEX`, allowing every address at a configured domain to be collected as a catch-all inbox. Mailpit does not send or relay captured mail unless relay functionality is configured separately. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | --------------------------------------------------------------------- | +| Web interface | `https://mailpit..ts.net` | +| Service port | `8025` | +| SMTP | TCP port `25` on the Docker host, forwarded to port `1025` of Mailpit | +| Image | `axllent/mailpit` | +| Data | `./mailpit-data/app/data` (SQLite database with the messages) | -In this setup, the `tailscale-mailpit` container runs Tailscale and owns the shared network namespace. The `mailpit` service uses Docker's `network_mode: service:tailscale` configuration, allowing Tailscale Serve to proxy the Mailpit web interface from `127.0.0.1:8025` to HTTPS on your Tailnet. +## Before you start -Only SMTP is published on the Docker host: +1. Set these values in `.env`: -- Mailpit web interface: Tailnet-only through Tailscale Serve on HTTPS port `443` -- Incoming SMTP: public host TCP port `25`, forwarded to Mailpit TCP port `1025` -- Tailscale Funnel: disabled + | Variable | Description | Example | + | -------------------------- | ----------------------------------------------------------- | ------------------ | + | `MAIL_DOMAIN_REGEX` | Regular expression for the recipients that Mailpit accepts | `'@example\.com$'` | + | `MAILPIT_MAX_MESSAGES` | Maximum number of stored messages; `0` disables this limit | `0` | + | `MAILPIT_MAX_AGE` | Maximum age of a message in hours or days | `90d` | + | `MAILPIT_MAX_MESSAGE_SIZE` | Maximum size of a message in MB | `50` | -## Key Features + Escape the dots in the regular expression. For example, `'@mail\.example\.com$'` accepts every recipient at `mail.example.com`. -- Catch-all email capture for a configurable domain -- Private web interface with Tailscale HTTPS -- Public SMTP delivery on the standard TCP port `25` -- Persistent SQLite message storage -- Configurable message count, age, and size limits -- Health checks for both Tailscale and Mailpit -- No outbound mail relay configured by default +2. Create an address record for the mail host and point the MX record of the domain to it. Replace the sample values with your public host name and IP address: -Some hosting providers block inbound or outbound SMTP traffic. Confirm that TCP port `25` is permitted before deploying this service. + ```dns + mail.example.com. A 203.0.113.10 + example.com. MX 10 mail.example.com. + ``` -## Environment Configuration + The MX target must resolve directly to the Docker host. Forward TCP port `25` through your firewall or router, and do not put the mail host behind an HTTP-only reverse proxy or CDN. -Update `.env` before starting the containers. The following values are required by `compose.yaml`: +3. Check that your provider allows traffic on TCP port `25`. Some hosting providers block it. -| Variable | Description | Example | -| -------------------------- | --------------------------------------------------------- | ---------------------------- | -| `MAIL_DOMAIN_REGEX` | Regular expression matching allowed recipients | `'@example\.com$'` | -| `MAILPIT_MAX_MESSAGES` | Maximum stored messages; `0` disables count-based pruning | `0` | -| `MAILPIT_MAX_AGE` | Maximum message age in hours or days | `90d` | -| `MAILPIT_MAX_MESSAGE_SIZE` | Maximum accepted message size in MB | `50` | +## Deviations from the standard setup -For a different domain, escape dots in the regular expression. For example, use `'@mail\.example\.com$'` to accept every recipient ending in `@mail.example.com`. +- **Published SMTP port.** The `ports` block is active. It publishes TCP port `25` of the Docker host and forwards it to port `1025` of Mailpit, so that mail servers on the internet can deliver messages. The web interface stays on your Tailnet. +- **Recipient filter.** `MP_SMTP_ALLOWED_RECIPIENTS` only accepts mail for the recipients that match `MAIL_DOMAIN_REGEX`. +- **Retention.** `compose.yaml` passes the limits from `.env` to Mailpit, which deletes messages beyond them. -## DNS Configuration +## First run -Create an address record for the mail host and point the domain's MX record to it. Replace the example values with your public hostname and IP address: +Nothing to set up. The web interface has no login. Send a message to an address at your domain and open the web interface to see it. -```dns -mail.example.com. A 203.0.113.10 -example.com. MX 10 mail.example.com. -``` +## Configuration -The MX target must resolve directly to the Docker host, and TCP port `25` must be forwarded through any external firewall or router. Do not proxy the mail hostname through an HTTP-only reverse proxy or CDN. +### Security -## Security Considerations +SMTP is open to the internet without authentication, so that other mail servers can deliver messages. `MAIL_DOMAIN_REGEX` limits the recipients, but Mailpit is a tool to test and inspect email and not a full mail server. Keep the web interface private, use firewall rules where they fit, update regularly, and do not keep sensitive mail longer than needed. -SMTP is intentionally exposed to the public internet without mailbox authentication so external mail servers can deliver messages. `MAIL_DOMAIN_REGEX` limits accepted recipients, but Mailpit is primarily an email testing and inspection tool rather than a full production mail server. Keep the web interface private, use firewall rules where appropriate, apply updates regularly, and avoid storing sensitive mail longer than necessary. - -## Files to Check - -Please check the following files before deployment: - -- `.env` — service images, Tailscale auth key, recipient restriction, and retention settings -- `compose.yaml` — public SMTP binding, Tailscale Serve configuration, and storage paths - -## Reference Material +## Links - [Mailpit documentation](https://mailpit.axllent.org/docs/) - [Mailpit runtime options](https://mailpit.axllent.org/docs/configuration/runtime-options/) diff --git a/services/mattermost/README.md b/services/mattermost/README.md index 444c745d..3891dfa2 100644 --- a/services/mattermost/README.md +++ b/services/mattermost/README.md @@ -1,40 +1,50 @@ -# Mattermost with Tailscale Sidecar Configuration +# Mattermost -This Docker Compose configuration sets up [Mattermost](https://mattermost.com/platform-overview/) with Tailscale as a sidecar container to securely manage team communication over a private Tailscale network. By integrating Tailscale, you can ensure that your Mattermost instance remains private and accessible only to authorized devices on your Tailscale network. +[Mattermost](https://mattermost.com/) is a collaboration platform for teams, with channels, direct messages, file sharing, and integrations. It is an open-source alternative to Slack. -## Mattermost +This stack runs Mattermost with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Mattermost](https://mattermost.com/platform-overview/) is an open-source, self-hosted collaboration platform for secure team communication and workflow automation, functioning as a secure alternative to Slack. It provides tools for chat, file sharing, and integrations, with an emphasis on data control and security for enterprise use, especially in high-stakes sectors like defense and critical infrastructure. The platform is designed for flexibility and extensibility, allowing for deep customization and integration with other tools and processes to manage complex workflows. +## At a glance -## Key Features +| Item | Value | +| ------------- | --------------------------------------------------------------------------------------------------------- | +| Web interface | `https://mattermost..ts.net` | +| Service port | `8065` | +| Images | `mattermost/mattermost-team-edition` | +| | `postgres:17-alpine` | +| Data | `./mattermost-data/config`, `data`, `logs`, `plugins`, `client/plugins`, and `bleve-indexes` (Mattermost) | +| | `./mattermost-data/postgres/data` (PostgreSQL database) | -- **Secure Messaging**: Offers public and private channels, direct messaging, and secure file sharing within teams and organizations. -- **Workflow Automation**: Includes features like Playbooks to streamline and automate complex processes and tasks. -- **Self-Hosting & Data Control**: Built to be self-hosted, giving IT administrators full control over data, security, and the platform's infrastructure. -- **Open-Source & Open Core**: Features an open-source core with an open-source edition and commercial, subscription-based editions that add advanced capabilities. -- **Extensive Integrations**: Designed for seamless integration with development tools and other enterprise software, such as GitLab. -- **Multi-Platform Support**: Available as web, desktop, and mobile applications for iOS, Android, Windows, and macOS. +## Before you start -## Configuration Overview +1. Create the Mattermost folders yourself and make user `2000` their owner. Docker creates missing folders as user `root`. The Mattermost image runs as user and group `2000` and then fails with `could not create config file: open /mattermost/config/config.json: permission denied`. Do not change the owner of the `postgres` folder, which PostgreSQL manages itself. -In this setup, the `tailscale-Mattermost` container runs Tailscale, which manages secure networking for the Mattermost service. The `Mattermost` service uses the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This ensures that Mattermost’s web interface and functionality are only accessible through the Tailscale network unless you enable host port mappings. + ```bash + DATA_DIR=mattermost-data + mkdir -p "$DATA_DIR"/{config,data,logs,plugins,client/plugins,bleve-indexes} + sudo chown -R 2000:2000 "$DATA_DIR"/{config,data,logs,plugins,client,bleve-indexes} + ``` -The stack stores Mattermost and PostgreSQL data under the local `${SERVICE}-data` directory, which is `mattermost-data` by default. The path variables in `.env` are relative to this service directory, so the stack does not depend on the shell's current PWD variable. + If you changed `SERVICE` in `.env`, set `DATA_DIR` to `-data`. -## Troubleshooting +2. Set these values in `.env`: -The Mattermost image runs as UID/GID `2000`. Docker creates missing bind-mount directories as `root:root`, and Mattermost then fails with: + - **`DOMAIN`.** The name of the device on your Tailnet, `mattermost..ts.net`. The stack builds the site address, `MM_SERVICESETTINGS_SITEURL`, from it. + - **`POSTGRES_USER` and `POSTGRES_PASSWORD`.** The login of the database. Replace the sample values. -```plain -app-mattermost | Error: failed to load configuration: could not create config file: open /mattermost/config/config.json: permission denied -``` +## Deviations from the standard setup -Create the Mattermost directories and set their owner before the first start. Run the commands from this service directory. If you changed `SERVICE` in `.env`, set `DATA_DIR` to `-data`. Do not change the owner of the `postgres` directory, which PostgreSQL manages itself. +- **Extra container.** The stack runs a `database` container with PostgreSQL, named `db-mattermost`. It uses the default Compose network, and Mattermost reaches it by its service name through Docker's DNS. Keep `TS_ACCEPT_DNS` disabled, because MagicDNS cannot resolve that name. +- **Data paths in `.env`.** The `*_PATH` variables in `.env` set the data folders. They are relative to this directory. +- **Reduced privileges.** Both containers set `no-new-privileges` and a limit on the number of processes. The database container has a read-only file system. +- **Service port.** Mattermost listens on port `8065`. `SERVICEPORT` in `.env` is only used by the optional `ports` block. -```bash -DATA_DIR=mattermost-data -mkdir -p "$DATA_DIR"/{config,data,logs,plugins,client/plugins,bleve-indexes} -sudo chown -R 2000:2000 "$DATA_DIR"/{config,data,logs,plugins,client,bleve-indexes} -``` +## First run -Reference - [Starting/Stopping Docker](https://github.com/mattermost/mattermost-docker/commit/37331ba3d7122aeb30272308dddf51ef70e2134c#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L146) +Open the web interface and create the first account, which becomes the system administrator. Then create your team. + +## Links + +- [Mattermost documentation](https://docs.mattermost.com/) +- [Mattermost Docker deployment](https://docs.mattermost.com/deployment-guide/server/deploy-containers.html) +- [Mattermost source code](https://github.com/mattermost/mattermost) diff --git a/services/mealie/README.md b/services/mealie/README.md index 2acd1851..35360ea6 100644 --- a/services/mealie/README.md +++ b/services/mealie/README.md @@ -1,21 +1,32 @@ -# Mealie with Tailscale Sidecar Configuration +# Mealie -This Docker Compose configuration sets up [**Mealie**](https://github.com/mealie-recipes/mealie/) with Tailscale as a sidecar container, enabling secure access to your personal recipe collection and meal planning platform from anywhere on your private Tailscale network. With this setup, your Mealie instance stays fully private and accessible only to your authorized devices. +[Mealie](https://mealie.io/) is a recipe manager and meal planner. You import a recipe from a web address, plan your meals, and build shopping lists. -## Mealie +This stack runs Mealie with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[**Mealie**](https://github.com/mealie-recipes/mealie/) is a self-hosted recipe management platform designed for home cooks, meal planners, and families. It provides a clean and modern interface to organize, import, and share recipes. Mealie also offers robust tools for planning meals, generating shopping lists, and storing culinary inspiration—all without relying on third-party services. +## At a glance -## Key Features +| Item | Value | +| ------------- | --------------------------------- | +| Web interface | `https://mealie..ts.net` | +| Service port | `9000` | +| Image | `ghcr.io/mealie-recipes/mealie` | +| Data | `./mealie-data` | -* **Recipe Management** – Create, edit, and store recipes with rich formatting and images. -* **Recipe Scraping** – Import recipes directly from popular websites. -* **Meal Planning** – Plan meals for the week or month with an easy-to-use calendar view. -* **Shopping List Generator** – Automatically create shopping lists based on your meal plan. -* **Multi-User Support** – Invite family members or housemates to collaborate. -* **Self-Hosted** – All your data remains under your control. -* **Private by Default with Tailscale** – Runs behind a Tailscale sidecar for private access only. +## Before you start -## Configuration Overview +Set `BASE_URL` in `compose.yaml` to the address of the web interface, `https://mealie..ts.net`. The sample value is `https://mealie.yourdomain.ts.net`. -In this deployment, the `tailscale-mealie` service runs the Tailscale client to establish a secure private network. The `mealie` container uses `network_mode: service:tailscale` to route its network traffic through the Tailscale network interface. This configuration ensures that the web UI is only accessible over Tailscale, protecting your recipes and personal data from public exposure. +## Deviations from the standard setup + +- **Memory limit.** The stack limits the `application` container to 1000 MB of memory. +- **No sign-up.** `ALLOW_SIGNUP` is `"false"`, so new users need an invitation from an administrator. + +## First run + +Open the web interface and log in with the default account `changeme@example.com` and password `MyPassword`. Mealie then asks you to set up your own account. Change the email address and the password right away. + +## Links + +- [Mealie documentation](https://docs.mealie.io/) +- [Mealie source code](https://github.com/mealie-recipes/mealie) diff --git a/services/memos/README.md b/services/memos/README.md index 3bb1bf6a..9fdf45b7 100644 --- a/services/memos/README.md +++ b/services/memos/README.md @@ -1,24 +1,31 @@ -# Memos with Tailscale Sidecar Configuration +# Memos -This Docker Compose configuration sets up **Memos** with a Tailscale sidecar container, allowing you to securely access your personal knowledge base over your private Tailnet without exposing it to the public internet. +[Memos](https://usememos.com/) is a note-taking service for quick thoughts. You write short notes in Markdown, tag them, and find them again in a timeline. -## Memos +This stack runs Memos with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Memos](https://github.com/usememos/memos) is a lightweight, open-source note-taking and knowledge management platform designed for capturing quick thoughts, ideas, and daily logs. It combines the simplicity of a personal notebook with the structure of a self-hosted knowledge base, making it ideal for developers, operators, and individuals who want full control over their notes. +## At a glance -By pairing Memos with Tailscale, you ensure that your notes remain private and accessible only to authorized devices on your Tailnet, eliminating the need for public exposure or complex reverse proxy setups. +| Item | Value | +| ------------- | -------------------------------- | +| Web interface | `https://memos..ts.net` | +| Service port | `5230` | +| Image | `neosmemo/memos:stable` | +| Data | `./memos-data` | -## Configuration Overview +## Before you start -In this setup, the `tailscale-memos` service runs Tailscale and manages secure networking. The `memos` service uses the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This ensures that Memos is only accessible through your Tailnet unless you explicitly expose ports. +Set `MEMOS_INSTANCE_URL` in `compose.yaml` to the address of the web interface, `https://memos..ts.net`. -## Files to check +## Deviations from the standard setup -Please verify the following before starting: +- **Database.** `MEMOS_DRIVER=sqlite` makes Memos store its data in a SQLite database in the data folder. -- `.env` // Must include `TS_AUTHKEY` for Tailscale authentication +## First run -## Resources +Open the web interface and sign up. The first account becomes the administrator. -- Official Repository: -- Documentation: +## Links + +- [Memos documentation](https://usememos.com/docs) +- [Memos source code](https://github.com/usememos/memos) diff --git a/services/metube/README.md b/services/metube/README.md index f7c0cdee..573615bd 100644 --- a/services/metube/README.md +++ b/services/metube/README.md @@ -1,11 +1,31 @@ -# Metube with Tailscale Sidecar Configuration +# MeTube -This Docker Compose configuration sets up [Metube](https://github.com/alexta69/metube) with Tailscale as a sidecar container to securely manage and access your self-hosted YouTube downloader over a private Tailscale network. By integrating Tailscale, you can ensure that your Metube instance remains private and accessible only to authorized devices on your Tailscale network. +[MeTube](https://github.com/alexta69/metube) is a web interface for `yt-dlp`. It downloads videos and audio from YouTube and many other sites to your server. -## Metube +This stack runs MeTube with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Metube](https://github.com/alexta69/metube) is a self-hosted YouTube downloader with playlist support. Allows you to download videos from YouTube and dozens of other sites. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | --------------------------------- | +| Web interface | `https://metube..ts.net` | +| Service port | `8081` | +| Image | `ghcr.io/alexta69/metube` | +| Data | `./downloads` | -In this setup, the `tailscale-metube` service runs Tailscale, which manages secure networking for the metube application. The `metube` service uses the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This ensures that metube’s web interface is only accessible through the Tailscale network (or locally, if preferred), providing enhanced privacy and security. +## Before you start + +Nothing beyond the [Quick Start](../../README.md#quick-start). + +## Deviations from the standard setup + +- **MagicDNS is enabled.** The stack sets `TS_ACCEPT_DNS=true`, so the containers resolve names through MagicDNS and not through Docker's DNS. +- **Download folder.** The downloads are in `./downloads`, not in a `./metube-data` folder. + +## First run + +MeTube has no login. Open the web interface, paste a link, and select **Download**. The files appear in `./downloads`. + +## Links + +- [MeTube documentation and source code](https://github.com/alexta69/metube) diff --git a/services/minecraft/README.md b/services/minecraft/README.md index 527b2007..3689d8c7 100644 --- a/services/minecraft/README.md +++ b/services/minecraft/README.md @@ -1,79 +1,48 @@ -# Minecraft Server with Tailscale Sidecar Configuration +# Minecraft Server -This Docker Compose configuration sets up a [Minecraft Java Edition](https://www.minecraft.net/) server with Tailscale as a sidecar container, enabling private multiplayer access over your Tailnet. No port forwarding or public IP required — only players on your Tailscale network can connect. +This stack runs a [Minecraft Java Edition](https://www.minecraft.net/) server with the [`itzg/minecraft-server`](https://docker-minecraft-server.readthedocs.io) image, which supports Vanilla, Paper, Fabric, Forge, and other server types. Players connect to it over your Tailnet. -## Minecraft +This stack runs Minecraft Server with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Minecraft](https://www.minecraft.net/) is one of the most popular sandbox games in the world, offering open-ended survival, building, and exploration gameplay. This configuration uses the [itzg/minecraft-server](https://hub.docker.com/r/itzg/minecraft-server) Docker image, the community standard with support for Vanilla, Paper, Fabric, Forge, and other server types. +## At a glance -## Key Features +| Item | Value | +| ------------- | ----------------------------------------------------------- | +| Web interface | None | +| Game server | `minecraft..ts.net`, TCP port `25565` | +| Image | `itzg/minecraft-server` | +| Data | `./minecraft-data` (world, configuration, and server files) | -* **Private multiplayer** — no router ports need to be opened; all traffic stays on your Tailnet. -* **MagicDNS hostname** — players connect using `minecraft..ts.net:25565`. -* **Multiple server types** — switch between Vanilla, Paper, Fabric, Forge, Spigot, and Bukkit via an environment variable. -* **Persistent world data** — world files and server config are stored in a named Docker volume. -* **Fully configurable** — server type, version, difficulty, player limit, MOTD, and memory are all set through `.env`. +## Before you start -## Networking Note +The defaults work without changes. You can adjust these values in `.env`: -Unlike web-based services in this repository, Minecraft uses **raw TCP on port 25565**. Tailscale Serve and Funnel only proxy HTTP/HTTPS traffic, so they are **not used here**. Instead, the Minecraft server listens directly on the Tailscale interface and players connect at: +| Variable | Default | Description | +| ------------------- | --------------------------------- | -------------------------------------------------------------- | +| `SERVER_TYPE` | `VANILLA` | Server software: VANILLA, PAPER, FABRIC, FORGE, SPIGOT, BUKKIT | +| `MINECRAFT_VERSION` | `LATEST` | Game version: LATEST or a fixed version such as 1.21.4 | +| `DIFFICULTY` | `normal` | Game difficulty: peaceful, easy, normal, hard | +| `MAX_PLAYERS` | `10` | Maximum number of players at the same time | +| `MOTD` | `A Minecraft Server on Tailscale` | Message in the server list | +| `MEMORY` | `2G` | Java heap size; increase it for larger worlds or more players | -```text -minecraft..ts.net:25565 -``` +## Deviations from the standard setup -No `serve.json` configuration is needed for this service. +- **No Tailscale Serve.** Minecraft uses its own protocol on TCP port `25565`, which Tailscale Serve does not forward. The server listens on that port of the Tailscale IP address of the device, and the stack has no Serve configuration. +- **License agreement.** `compose.yaml` sets `EULA=TRUE`, which accepts the [Minecraft End User License Agreement](https://www.minecraft.net/eula) for you. -## Configuration Overview +## First run -In this setup, the `tailscale-minecraft` service runs the Tailscale client to join your private mesh network. The `minecraft` service is configured with `network_mode: service:tailscale`, so all network traffic for the game server is routed through the Tailscale container. The Minecraft server binds TCP port 25565, which is reachable only from devices on your Tailnet. +1. Start the stack. The first start takes a while, because the image downloads the server. +2. In Minecraft, select **Multiplayer** > **Add Server** and enter `minecraft..ts.net`. -## Setup +All players must be on your Tailnet, or you must share the device with them. -1. Clone the repository and navigate to the service directory: +## Configuration - ```bash - git clone https://github.com/tailscale-dev/ScaleTail.git - cd ScaleTail/services/minecraft - ``` +- **Bedrock Edition.** Bedrock uses UDP port `19132` and another server type, which this stack does not set up. -2. Edit `.env` and paste in your Tailscale auth key (from [https://login.tailscale.com/admin/settings/keys](https://login.tailscale.com/admin/settings/keys)). +## Links -3. (Optional) Adjust `SERVER_TYPE`, `MEMORY`, `MAX_PLAYERS`, or other variables in `.env`. - -4. Start the stack: - - ```bash - docker compose up -d - ``` - -5. Find your Tailnet name in the [Tailscale admin console](https://login.tailscale.com/admin/machines). - -6. Connect in Minecraft: **Multiplayer** → **Add Server** → `minecraft..ts.net` - -## Connecting - -* All players must be on the same Tailnet (or have been shared access to the node). -* `ONLINE_MODE=false` allows offline/non-premium accounts but reduces security — only use this on trusted networks. -* Bedrock Edition uses UDP port 19132, which is not proxied through Tailscale Serve. Bedrock players can still connect directly via the Tailscale IP on port 19132, but this requires using the Bedrock edition of itzg/minecraft-server (set `TYPE=BEDROCK`) and is outside the scope of this configuration. - -## Environment Variables - -| Variable | Default | Description | -| --- | --- | --- | -| `TS_AUTHKEY` | _(empty)_ | Tailscale auth key from the admin console | -| `SERVER_TYPE` | `PAPER` | Server software: VANILLA, PAPER, FABRIC, FORGE, SPIGOT, BUKKIT | -| `MINECRAFT_VERSION` | `LATEST` | Game version: LATEST or a pinned version like 1.21.4 | -| `DIFFICULTY` | `normal` | Game difficulty: peaceful, easy, normal, hard | -| `MAX_PLAYERS` | `10` | Maximum concurrent players | -| `MOTD` | `A Minecraft Server on Tailscale` | Message shown in the server browser | -| `MEMORY` | `2G` | JVM heap size — increase for larger worlds or player counts | -| `ONLINE_MODE` | `true` | Require valid Minecraft accounts (set false for offline/LAN play) | - -## Useful Links - -* [itzg/minecraft-server on Docker Hub](https://hub.docker.com/r/itzg/minecraft-server) -* [itzg/minecraft-server documentation](https://docker-minecraft-server.readthedocs.io) -* [Tailscale Serve docs](https://tailscale.com/kb/1242/tailscale-serve) -* [Tailscale Funnel docs](https://tailscale.com/kb/1223/funnel) -* [Tailscale Docker guide](https://tailscale.com/blog/docker-tailscale-guide) +- [itzg/minecraft-server documentation](https://docker-minecraft-server.readthedocs.io) +- [itzg/minecraft-server on Docker Hub](https://hub.docker.com/r/itzg/minecraft-server) diff --git a/services/miniflux/README.md b/services/miniflux/README.md index 7dbfc6e8..c1b9ce8e 100644 --- a/services/miniflux/README.md +++ b/services/miniflux/README.md @@ -1,27 +1,38 @@ -# Miniflux with Tailscale Sidecar Configuration +# Miniflux -This Docker Compose configuration sets up [Miniflux](https://github.com/miniflux/v2) with Tailscale as a sidecar container, enabling secure access to your minimalist feed reader over a private Tailscale network. With this setup, your Miniflux instance remains fully private and accessible only from authorized devices. +[Miniflux](https://miniflux.app/) is a minimalist feed reader for RSS, Atom, and JSON feeds. It is fast and has a clean interface without distractions. -## Miniflux +This stack runs Miniflux with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Miniflux](https://miniflux.app/) is a minimalist and opinionated feed reader. It is designed to be fast, simple, and efficient, supporting RSS, Atom, and JSON feeds. Miniflux is focused on reading and offers a clean, distraction-free user interface. +## At a glance -## Key Features +| Item | Value | +| ------------- | ------------------------------------------ | +| Web interface | `https://miniflux..ts.net` | +| Service port | `8080` | +| Images | `miniflux/miniflux` | +| | `postgres:15-alpine` | +| Data | `./miniflux-data/db` (PostgreSQL database) | -* **Minimalist Design** – Focused purely on readability and efficiency. -* **Fast & Lightweight** – Written in Go, ensuring high performance and low resource usage. -* **Feed Support** – Supports RSS, Atom, and JSON feeds. -* **Privacy Focused** – Removes pixel trackers and ads from articles. -* **Self-Hosted** – Keep full control of your reading data. -* **Private by Default with Tailscale** – Secured with Tailscale, accessible only to you. +## Before you start -## Configuration Overview +Set these values in `.env`: -In this deployment, the `tailscale-miniflux` service runs the Tailscale client to establish a secure private network. The `miniflux` application and its `postgres` database both use `network_mode: service:tailscale`. This means all services share the same network namespace, allowing them to communicate via `localhost` and keeping the application reachable only via the Tailscale network. +- **`TAILNET_NAME`.** Your Tailnet name with `.ts.net`. `compose.yaml` builds the base address of Miniflux as `https://.`. +- **`ADMIN_USERNAME` and `ADMIN_PASSWORD`.** The administrator account that Miniflux creates at the first start. The password needs at least six characters. +- **`POSTGRES_PASSWORD`.** The password of the database. -## Files to check +## Deviations from the standard setup -Please verify the following files and variables before deploying: +- **Extra container.** The stack runs a `db` container with PostgreSQL. It uses the network of the `tailscale` container as well, so Miniflux reaches it at `localhost`. PostgreSQL therefore also listens on port `5432` of the Tailscale IP address of the device. +- **Automatic setup.** `RUN_MIGRATIONS=1` and `CREATE_ADMIN=1` make Miniflux prepare the database and create the administrator at the start. -* `.env` — define `SERVICE`, `IMAGE_URL`, `TS_AUTHKEY`, `ADMIN_USERNAME`, `ADMIN_PASSWORD`, and database credentials. -* `compose.yaml` — confirm volume mappings and environment variables. +## First run + +Open the web interface and log in with the administrator account from `.env`. + +## Links + +- [Miniflux documentation](https://miniflux.app/docs/) +- [Miniflux configuration parameters](https://miniflux.app/docs/configuration.html) +- [Miniflux source code](https://github.com/miniflux/v2) diff --git a/services/miniqr/README.md b/services/miniqr/README.md index b5605aa6..45352bbe 100644 --- a/services/miniqr/README.md +++ b/services/miniqr/README.md @@ -1,19 +1,31 @@ -# Mini-QR with Tailscale Sidecar Configuration +# Mini QR -This Docker Compose configuration sets up **[Mini-QR](https://github.com/lyqht/mini-qr)** with Tailscale as a sidecar container to securely access your self-hosted QR code generation tool over a private Tailscale network. By integrating Tailscale, you can ensure that your Mini-QR instance is only accessible to authorized devices within your private network, adding an extra layer of privacy and security. +[Mini QR](https://github.com/lyqht/mini-qr) creates and scans QR codes in your browser. You style the code with colours, shapes, and a logo and export it as an image. -## Mini-QR +This stack runs Mini QR with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Mini-QR](https://github.com/lyqht/mini-qr) is a **minimalist, self-hosted web app** for quickly generating QR codes on the fly. It features a sleek and simple interface that works well on both desktop and mobile, making it ideal for sharing links, text, or other short data via QR. It’s lightweight, fast, and requires no external services. Pairing it with Tailscale ensures that only trusted devices can access your QR generation tool—perfect for local, secure usage scenarios. +## At a glance -## Key Features +| Item | Value | +| ------------- | ---------------------------------- | +| Web interface | `https://mini-qr..ts.net` | +| Service port | `8080` | +| Image | `ghcr.io/lyqht/mini-qr` | +| Data | None | -- **Quick QR Generation** – Instantly generate QR codes from text or URLs. -- **Mobile-Friendly UI** – Works smoothly on mobile and desktop devices. -- **No Tracking, No Dependencies** – Lightweight and privacy-respecting. -- **Self-Hosted** – Full control, no reliance on third-party QR services. -- **Secure Access with Tailscale** – Limit access to authorized devices via your private network. +## Before you start -## Configuration Overview +Nothing beyond the [Quick Start](../../README.md#quick-start). -In this setup, the `tailscale-miniqr` service runs Tailscale, which handles secure networking for the Mini-QR service. The `mini-qr` service uses the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This setup ensures that the Mini-QR web interface is only accessible via your Tailscale network (or locally if preferred), giving you complete control over access and visibility. +## Deviations from the standard setup + +- **Device name.** `SERVICE` in `.env` is `mini-qr`, which differs from the name of this directory. +- **No data folder.** Mini QR runs in your browser and stores nothing on the server, so the stack has no application data. + +## First run + +Nothing to set up. Open the web interface. + +## Links + +- [Mini QR documentation and source code](https://github.com/lyqht/mini-qr) diff --git a/services/nanote/README.md b/services/nanote/README.md index 83500e38..80483fd8 100644 --- a/services/nanote/README.md +++ b/services/nanote/README.md @@ -1,19 +1,30 @@ -# Nanote with Tailscale Sidecar Configuration +# Nanote -This Docker Compose configuration sets up **[Nanote](https://github.com/omarmir/nanote)** with Tailscale as a sidecar container to securely manage and access your self-hosted note-taking application over a private Tailscale network. By integrating Tailscale, you can ensure that your Nanote instance remains private and accessible only to authorized devices within your Tailscale network. +[Nanote](https://github.com/omarmir/nanote) is a lightweight note-taking application. It stores your notes as Markdown files in folders, so that you can use them with other tools as well. -## Nanote +This stack runs Nanote with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Nanote](https://github.com/omarmir/nanote) is a lightweight, self-hosted note-taking application designed for simplicity and speed. It provides a distraction-free environment to jot down quick notes, ideas, or reminders without the complexity of traditional note-taking apps. By integrating Tailscale, you can keep your Nanote instance secure and accessible only within your private network. +## At a glance -## Key Features +| Item | Value | +| ------------- | ---------------------------------------------- | +| Web interface | `https://nanote..ts.net` | +| Service port | `3000` | +| Image | `omarmir/nanote` | +| Data | `./nanote-data` (your notes as Markdown files) | -- **Minimalist Design** – A clean and distraction-free interface for note-taking. -- **Fast & Lightweight** – Optimized for quick note-taking without unnecessary bloat. -- **Self-Hosted Privacy** – Keep your notes secure and under your control. -- **Markdown Support** – Write notes in Markdown for easy formatting. -- **Secure Access with Tailscale** – Restrict access to only authorized devices within your private network. +## Before you start -## Configuration Overview +Replace `` in `SECRET_KEY` in `compose.yaml` with your own secret. Nanote uses it as the key to log in. -In this setup, the `tailscale-nanote` service runs Tailscale, which manages secure networking for the Nanote service. The `nanote` service uses the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This ensures that Nanote’s web interface and note storage are only accessible through the Tailscale network (or locally, if preferred), adding an extra layer of security and privacy to your note-taking workflow. +## Deviations from the standard setup + +None. + +## First run + +Open the web interface and log in with the value of `SECRET_KEY`. + +## Links + +- [Nanote documentation and source code](https://github.com/omarmir/nanote) diff --git a/services/navidrome/README.md b/services/navidrome/README.md index 4ed224e2..55d712e7 100644 --- a/services/navidrome/README.md +++ b/services/navidrome/README.md @@ -1,22 +1,34 @@ -# Navidrome with Tailscale Sidecar Configuration +# Navidrome -This Docker Compose configuration sets up [Navidrome](https://github.com/navidrome/navidrome) with Tailscale as a sidecar container, enabling secure, private access to your music server over your Tailscale network. With this configuration, Navidrome is never exposed to the public internet, and access is limited to authorized devices on your Tailnet. +[Navidrome](https://www.navidrome.org/) is a music server. It streams your own music collection to its web player and to the many apps that support the Subsonic API. -## Navidrome +This stack runs Navidrome with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -Navidrome is a self-hosted music streaming server and web-based player. It allows you to stream your personal music collection from anywhere, across multiple devices. Compatible with the Subsonic API, it supports a wide range of third-party apps. With a sleek interface, low resource usage, and fast scanning, Navidrome is the ideal solution for building your own private Spotify-like experience. +## At a glance -## Key Features +| Item | Value | +| ------------- | ------------------------------------------------------------- | +| Web interface | `https://navidrome..ts.net` | +| Service port | `4533` | +| Image | `deluan/navidrome` | +| Data | `./navidrome-data/data` (database and cache) | +| | The folder that you mount at `/music` (your music, read-only) | -* **Modern Music Streaming** – Web-based and mobile-friendly interface for streaming your own library. -* **Subsonic API Compatible** – Works with dozens of mobile and desktop apps. -* **Multi-User Support** – Create accounts with individual libraries and permissions. -* **Lightweight & Fast** – Runs well even on low-powered devices. -* **Cross-Platform** – Works on Linux, Windows, macOS, and ARM devices (like Raspberry Pi). -* **Private by Default with Tailscale** – Securely accessible only from your own devices. +## Before you start -## Configuration Overview +Replace `/path/to/your/music/folder` in `compose.yaml` with the absolute path of the folder on the Docker host that holds your music. -In this setup, the `tailscale-navidrome` container runs the Tailscale client and forms a private mesh network. The `navidrome` container is configured with `network_mode: service:tailscale`, which routes all of Navidrome’s traffic through Tailscale. This ensures that your music server is never exposed publicly, and can only be accessed from devices authenticated through your Tailscale Tailnet. +## Deviations from the standard setup -Before starting the stack, replace `/path/to/your/music/folder` in `compose.yaml` with the absolute host directory that contains your music library. +- **Time zone.** `compose.yaml` does not pass `TZ` to the container. + +## First run + +Open the web interface and create the administrator account. Navidrome then scans your music folder. + +In Subsonic apps, use `https://navidrome..ts.net` as the server address. The device must be connected to your Tailnet. + +## Links + +- [Navidrome documentation](https://www.navidrome.org/docs/) +- [Navidrome source code](https://github.com/navidrome/navidrome) diff --git a/services/nessus/README.md b/services/nessus/README.md index 91f309c5..0ec6741e 100644 --- a/services/nessus/README.md +++ b/services/nessus/README.md @@ -1,27 +1,34 @@ -# Nessus with Tailscale Sidecar Configuration +# Nessus -> ⚠️ **Important:** This container has no ability for persistent storage - your configuration will be lost when restarting the instance. +[Nessus](https://www.tenable.com/products/nessus) is a vulnerability scanner. It scans the systems in your network and reports vulnerabilities, configuration errors, and compliance issues. -This Docker Compose configuration sets up **[Nessus](https://www.tenable.com/products/nessus)** with Tailscale as a sidecar container to securely manage and access your vulnerability assessment tool over a private Tailscale network. By integrating Tailscale, you can ensure that your Nessus instance remains private and accessible only to authorized devices on your Tailscale network. +[Nessus Essentials](https://www.tenable.com/products/nessus/nessus-essentials) is free for personal use and scans up to 16 IP addresses. -## Nessus +This stack runs Nessus with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Nessus](https://www.tenable.com/products/nessus) is one of the most widely used vulnerability assessment tools, designed to help identify and remediate security issues in IT environments. With powerful scanning capabilities, Nessus provides detailed reports on system vulnerabilities, configuration errors, and compliance issues. By pairing Nessus with Tailscale, you can further secure your vulnerability management setup by restricting access to authorized devices within your private network. +## At a glance -### Nessus Essentials: Free for Personal Use +| Item | Value | +| ------------- | --------------------------------------------- | +| Web interface | `https://nessus..ts.net` | +| Service port | `8834` (HTTPS with a self-signed certificate) | +| Image | `tenable/nessus:latest-ubuntu` | +| Data | None on the host | -Nessus Essentials offers a free version of the tool for personal and home use, [request your license here](https://www.tenable.com/products/nessus/nessus-essentials). It allows scanning up to **16 IP addresses**, making it an excellent choice for individuals looking to improve the security of their home networks. Despite being a free version, Nessus Essentials provides access to many of the powerful scanning capabilities that Nessus is known for, making it ideal for learning or small-scale vulnerability assessments. +## Before you start -## Key Features +Request an activation code, for example for [Nessus Essentials](https://www.tenable.com/products/nessus/nessus-essentials). You need it in the setup. -- **Comprehensive Scanning**: Identify vulnerabilities, misconfigurations, and compliance violations across networks. -- **Detailed Reporting**: Generate in-depth reports to prioritize and remediate security issues effectively. -- **Self-Hosted**: Maintain full control over your scanning environment with a locally hosted instance. -- **Customizable Policies**: Tailor scans to meet your organization’s unique security needs. -- **Free Essentials Model**: Start for free with up to 16 IPs using Nessus Essentials. +## Deviations from the standard setup -## Configuration Overview +- **No data folder.** The stack has no volumes for Nessus. Your settings, scans, and license activation are lost when the container is recreated, for example after an image update. +- **Serve forwards to HTTPS.** Nessus serves its web interface on port `8834` with a self-signed certificate. Tailscale Serve forwards to it with `https+insecure`. -In this setup, the `tailscale-nessus` service runs Tailscale, which manages secure networking for the Nessus service. The `nessus` service uses the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This ensures that Nessus’ web interface and scanning functionalities are only accessible through the Tailscale network (or locally, if preferred), adding an additional layer of security to your vulnerability management infrastructure. +## First run -For additional configuration (environment variables) - please refer to the [Tenable documentation](https://docs.tenable.com/nessus/Content/DeployNessusDocker.htm). +Open the web interface and follow the setup. You choose the product, enter your activation code, and create the administrator account. Nessus then downloads and compiles its plugins, which takes a while. + +## Links + +- [Deploy Nessus as a Docker image](https://docs.tenable.com/nessus/Content/DeployNessusDocker.htm) +- [Nessus documentation](https://docs.tenable.com/nessus/) diff --git a/services/netbox/README.md b/services/netbox/README.md index c9652eaf..b2a9a57a 100644 --- a/services/netbox/README.md +++ b/services/netbox/README.md @@ -1,22 +1,55 @@ -# Netbox with Tailscale Sidecar Configuration +# NetBox -This Docker Compose configuration sets up [Netbox](https://github.com/netbox-community/netbox) with Tailscale as a sidecar container to securely access your Network layout over a private Tailscale network. By using Tailscale in a sidecar configuration, you can enhance the security and privacy, ensuring that they are only accessible within your Tailscale network. +[NetBox](https://netboxlabs.com/oss/netbox/) is the source of truth for your network. You document your IP addresses, racks, devices, connections, and circuits in it. -## Netbox +This stack runs NetBox with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Netbox](https://github.com/netbox-community/netbox) exists to empower network engineers. Since its release in 2016, it has become the go-to solution for modeling and documenting network infrastructure for thousands of organizations worldwide. As a successor to legacy IPAM and DCIM applications, NetBox provides a cohesive, extensive, and accessible data model for all things networked. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | --------------------------------------------------------------------- | +| Web interface | `https://netbox..ts.net` | +| Service port | `8080` | +| Images | `docker.io/netboxcommunity/netbox` | +| | `docker.io/postgres:17-alpine` | +| | `docker.io/valkey/valkey:8.1-alpine` | +| Data | `./netbox/media`, `./netbox/reports`, and `./netbox/scripts` (NetBox) | +| | `./netbox/postgres/data` (PostgreSQL database) | +| | `./netbox/redis/data` and `./netbox/redis/cache` (Valkey) | +| | `./config` (NetBox configuration files, also used by Tailscale) | -In this setup, the `tailscale-netbox` service runs Tailscale, which manages secure networking for the Netbox application. The `netbox` application uses the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This setup ensures that your Netbox application is only accessible through the Tailscale network (or local as well, if preferred). +## Before you start -## Files to check +Set these values in `.env`. Compose stops with an error if one of them is empty. -Please check the following contents for validity as some variables need to be defined upfront. +- **`SUPER_SECRET`.** The base value for the passwords of PostgreSQL and Valkey. Use letters and digits only. Generate one with `openssl rand -hex 16`. PostgreSQL applies its password only when it first creates the database. +- **`SECRET_KEY`.** A random value of at least 50 characters. Generate one with `openssl rand -base64 48`. -- `.env` - - Required: `TS_AUTHKEY` - - Required: `SUPER_SECRET`, the base value for the PostgreSQL and Redis passwords. Use letters and digits only. Generate it with `openssl rand -hex 16`. - - Required: `SECRET_KEY`, at least 50 characters. Generate it with `openssl rand -base64 48`. +## Deviations from the standard setup -Compose stops with an error if `SUPER_SECRET` or `SECRET_KEY` is empty. PostgreSQL applies the database password only when it first creates the database. If you are upgrading, set `SUPER_SECRET` to the value from your previous `.env`, including the old default if you never changed it. Otherwise NetBox cannot authenticate to the existing database. +- **Extra containers.** The stack runs `netbox-worker`, `postgres`, `redis`, and `redis-cache`. The worker uses the network of the `tailscale` container, like NetBox itself. The other three use the default Compose network, and NetBox reaches them by their container name through Docker's DNS. Keep `TS_ACCEPT_DNS` disabled, because MagicDNS cannot resolve these names. +- **Service and container names.** The application service is called `netbox`, not `application`, and the containers are named `netbox`, `worker-netbox`, `netbox-postgres`, `netbox-redis`, and `netbox-rediscache`. +- **Configuration files.** This directory contains the NetBox configuration files in `./config`, which the stack mounts read-only. The `tailscale` container stores its files in the same folder. +- **Data folder.** The data is in `./netbox`, not in a `./netbox-data` folder. +- **The containers read the whole `.env` file.** All containers load `.env` through `env_file`. Every variable in that file, including `TS_AUTHKEY`, is therefore present in their environment. +- **No administrator at the first start.** `SKIP_SUPERUSER=true` in `.env` stops NetBox from creating a default administrator. + +## First run + +The first start takes about four minutes, because NetBox prepares its database. Then create the administrator account: + +```bash +docker compose exec netbox /opt/netbox/netbox/manage.py createsuperuser +``` + +Open the web interface and log in with that account. + +## Upgrading + +If you are upgrading, set `SUPER_SECRET` to the value from your previous `.env`, including the old default if you never changed it. Otherwise NetBox cannot log in to the existing database. + +## Links + +- [NetBox documentation](https://netboxlabs.com/docs/netbox/) +- [netbox-docker wiki](https://github.com/netbox-community/netbox-docker/wiki) +- [NetBox source code](https://github.com/netbox-community/netbox) diff --git a/services/newwallpaperwhodis/README.md b/services/newwallpaperwhodis/README.md index 51fe0bdd..ce3b292f 100644 --- a/services/newwallpaperwhodis/README.md +++ b/services/newwallpaperwhodis/README.md @@ -1,29 +1,36 @@ -# NewWallpaperWhoDis with Tailscale Sidecar Configuration +# NewWallpaperWhoDis -This Docker Compose configuration sets up **NewWallpaperWhoDis** with a Tailscale sidecar container, enabling secure, private access to your self-hosted wallpaper manager over your Tailnet. With this setup, your NewWallpaperWhoDis instance is **not exposed to the public internet** and is only accessible from authorized devices connected via Tailscale. +[NewWallpaperWhoDis](https://newwallpaperwhodis.web.app/) is a wallpaper server. It turns browsers, tablets, smart TVs, and dashboards into displays that rotate through your wallpaper collection, and you manage the collection as plain files. -## NewWallpaperWhoDis +This stack runs NewWallpaperWhoDis with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[**NewWallpaperWhoDis**](https://github.com/upioneer/NewWallpaperWhoDis) is a lightweight, self-hosted wallpaper manager designed to turn browsers, tablets, smart TVs, Raspberry Pis, dashboards, and other display endpoints into dynamic smart displays. It uses a simple flat-file workflow, so wallpaper collections can be managed by placing images into directories instead of maintaining a traditional database-heavy media system. +## At a glance -The application scans your wallpaper files, processes useful metadata such as aspect ratio, orientation, and luminosity, and serves wallpapers through configurable rotation profiles. This makes it useful for dashboards, wall-mounted displays, digital signage-style setups, home labs, offices, and any environment where you want centrally managed wallpaper rotation without manually touching each display. +| Item | Value | +| ------------- | --------------------------------------------- | +| Web interface | `https://newwallpaperwhodis..ts.net` | +| Service port | `3000` | +| Image | `ghcr.io/upioneer/newwallpaperwhodis` | +| Data | `./wallpapers` (your wallpaper files) | +| | `./data` (settings and metadata) | -## Key Features +## Before you start -- 🖼️ Self-hosted wallpaper management for displays and browser-based endpoints -- 📁 Flat-file image library workflow with simple folder-based collection management -- 🔄 Dynamic wallpaper rotation through customizable profiles -- 🧭 Central web interface for managing wallpapers and endpoints -- 📺 Suitable for smart TVs, tablets, dashboards, Raspberry Pis, and kiosk-style screens -- 🧩 Lightweight deployment without a traditional relational database requirement -- 🔐 Tailnet-only access when paired with the included Tailscale sidecar +Nothing beyond the [Quick Start](../../README.md#quick-start). -## Usage Notes +## Deviations from the standard setup -For display devices such as smart TVs, tablets, or dashboards, open the relevant NewWallpaperWhoDis player URL in a browser. Once the endpoint is connected, wallpaper behavior can be managed centrally from the web interface without needing to reconfigure the device directly. +- **Image is set in `compose.yaml`.** The stack does not use `IMAGE_URL`. +- **Data folders.** The data is in `./data` and `./wallpapers`, not in a `./newwallpaperwhodis-data` folder. +- **Service port.** The application listens on port `3000`. `SERVICEPORT` in `.env` is only the host port of the optional `ports` block. -## References +## First run -- [NewWallpaperWhoDis Website](https://newwallpaperwhodis.web.app/) -- [NewWallpaperWhoDis GitHub Repository](https://github.com/upioneer/NewWallpaperWhoDis) -- [Tailscale Docker Documentation](https://tailscale.com/kb/1282/docker) +1. Put your wallpapers in `./wallpapers`. +2. Open the web interface to manage the collection and the rotation profiles. +3. On each display device, open the player address from the web interface in a browser. You then control what the device shows from the web interface. + +## Links + +- [NewWallpaperWhoDis website](https://newwallpaperwhodis.web.app/) +- [NewWallpaperWhoDis source code](https://github.com/upioneer/NewWallpaperWhoDis) diff --git a/services/next-explorer/README.md b/services/next-explorer/README.md index 2cf4ce39..f4c91d5b 100644 --- a/services/next-explorer/README.md +++ b/services/next-explorer/README.md @@ -1,13 +1,39 @@ -# NextExplorer with Tailscale Sidecar Configuration +# NextExplorer -This Docker Compose configuration sets up [NextExplorer](https://github.com/nxzai/NextExplorer) with Tailscale as a sidecar container to securely manage file system over a private Tailscale network. By using Tailscale in a sidecar configuration, you can enhance the security and privacy of your Next Explorer instance, ensuring that it is only accessible within your Tailscale network. +[NextExplorer](https://github.com/nxzai/NextExplorer) is a file explorer for your server. You browse, upload, download, and edit the files of a folder in your browser. -## NextExplorer +This stack runs NextExplorer with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[NextExplorer](https://github.com/nxzai/NextExplorer) is a modern, self-hosted file explorer designed for teams, creative agencies, and homelabs that need both a polished user interface and fine-grained access control. It ships as a single Docker container, mounts any number of volumes, and pairs seamlessly with reverse proxies or zero-trust networks. Whether you're organizing project assets for a small studio or providing secure file access across a household, NextExplorer delivers a responsive, feature-rich experience out of the box. This configuration leverages Tailscale to securely connect to your NextExplorer instance, protecting your file management interface from unauthorized access. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | ------------------------------------------------------------------------- | +| Web interface | `https://file-explorer..ts.net` | +| Service port | `3000` | +| Image | `nxzai/explorer` | +| Data | `./config` (configuration and database) | +| | `./cache` (thumbnails and unfinished uploads) | +| | The folder from `ACCESS_PATH` (your files, `/mnt/Files` in the container) | -In this setup, the `tailscale` service runs Tailscale, which manages secure networking for NextExplorer. The `application` service uses Docker's `network_mode: service:tailscale` configuration. This keeps the management interface on your Tailnet unless you enable the optional host port mapping. +## Before you start -Set `ACCESS_PATH` in `.env` to an absolute host directory before starting the stack. NextExplorer mounts that directory at `/mnt/Files`. Replace the sample `SESSION_SECRET` and `PUBLIC_URL` values with deployment-specific values when those settings are used. +Set these values in `.env`: + +- **`ACCESS_PATH`.** The absolute path of the folder on the Docker host that NextExplorer should show. +- **`SESSION_SECRET`.** A long random value. Generate one with `openssl rand -base64 32`. +- **`PUBLIC_URL`.** The address of the web interface, `https://file-explorer..ts.net`. NextExplorer uses it for its cookies, so use this address to open the web interface. + +## Deviations from the standard setup + +- **Device name.** `SERVICE` in `.env` is `file-explorer`, which differs from the name of this directory. +- **Shared configuration folder.** NextExplorer stores its configuration in `./config`, the folder that also holds the Tailscale configuration files. +- **Data folders.** The data is in `./config` and `./cache`, not in a `./file-explorer-data` folder. +- **User and group.** `PUID` and `PGID` come from `.env`. + +## First run + +Open the web interface. NextExplorer asks you to create the first account. + +## Links + +- [NextExplorer documentation and source code](https://github.com/nxzai/NextExplorer) diff --git a/services/nodered/README.md b/services/nodered/README.md index 7c01ac56..a8d3db60 100644 --- a/services/nodered/README.md +++ b/services/nodered/README.md @@ -1,20 +1,37 @@ -# Node-RED with Tailscale Sidecar Configuration +# Node-RED -This Docker Compose configuration sets up [Node-RED](https://github.com/node-red/node-red) with Tailscale as a sidecar container to securely access and manage your flow-based programming tool over a private Tailscale network. By using Tailscale in a sidecar configuration, you can enhance the security and privacy of your Node-RED instance, ensuring it is only accessible within your Tailscale network. +[Node-RED](https://nodered.org/) is a low-code tool for event-driven applications. You connect devices, APIs, and online services by wiring nodes together in a flow editor in your browser. -## Node-RED +This stack runs Node-RED with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Node-RED](https://github.com/node-red/node-red) is a low-code programming tool for event-driven applications, designed to connect devices, APIs, and online services through an intuitive, browser-based flow editor. It’s widely used for IoT, automation, and integration tasks, offering a powerful yet user-friendly way to build workflows. This configuration leverages Tailscale to securely connect to your Node-RED instance, ensuring that your workflows and configurations are protected from unauthorized access and accessible only via your private Tailscale network. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | ------------------------------------------------------------------ | +| Web interface | `https://nodered..ts.net` | +| Service port | `1880` | +| Image | `nodered/node-red` | +| Data | `./nodered-data/app/config` (flows, settings, and installed nodes) | -In this setup, the `tailscale-node-red` service runs Tailscale, which manages secure networking for the Node-RED service. The `node-red` service uses the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This ensures that Node-RED’s web interface is only accessible through the Tailscale network (or locally, if preferred), providing an additional layer of security and privacy for your flow-based programming environment. +## Before you start -## Volume Permissions +Create the data folder yourself and make user `1000` its owner. Docker creates missing folders as user `root`. The Node-RED image runs as user and group `1000`, and it then exits with `EACCES` when it copies `settings.js` into `/data`. -The Node-RED image runs as UID/GID `1000`. Docker creates missing bind-mount directories as `root:root`, and Node-RED then exits with `EACCES` when it copies `settings.js` into `/data`. Create the data directory before the first start: - -```sh +```bash mkdir -p nodered-data/app/config sudo chown -R 1000:1000 nodered-data ``` + +## Deviations from the standard setup + +None. + +## First run + +Open the web interface. The flow editor has no login by default, so everyone who can reach the device on your Tailnet can change your flows. See [Securing Node-RED](https://nodered.org/docs/user-guide/runtime/securing-node-red) to add one. + +## Links + +- [Node-RED documentation](https://nodered.org/docs/) +- [Node-RED in Docker](https://nodered.org/docs/getting-started/docker) +- [Node-RED source code](https://github.com/node-red/node-red) diff --git a/services/ntfy/README.md b/services/ntfy/README.md index 6e3284f7..3c203f77 100644 --- a/services/ntfy/README.md +++ b/services/ntfy/README.md @@ -1,13 +1,63 @@ -# ntfy with Tailscale Sidecar Configuration +# ntfy -This Docker Compose configuration sets up [ntfy](https://ntfy.sh/) with Tailscale as a sidecar container to securely deliver push notifications over a private Tailscale network. By integrating Tailscale in a sidecar configuration, you enhance the privacy and security of your ntfy instance, ensuring it is only accessible within your Tailscale network. +[ntfy](https://ntfy.sh/) is a notification service. Scripts and applications publish messages to a topic with a simple HTTP request, and your phone or browser receives them. -## ntfy +This stack runs ntfy with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[ntfy](https://ntfy.sh/) is a simple HTTP-based pub/sub notification service for sending push notifications to your devices and services. It supports sending messages via simple HTTP requests, with clients available for many platforms. By pairing ntfy with Tailscale, your notification broker becomes securely reachable through a zero-config mesh VPN, preventing unauthorized access over the public internet while keeping delivery fast and reliable. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | ----------------------------------------------- | +| Web interface | `https://ntfy..ts.net` | +| Service port | `80` | +| Image | `binwiederhier/ntfy` | +| Data | `./ntfy-data/etc` (configuration, `server.yml`) | +| | `./ntfy-data/cache` (message cache) | -In this setup, the `tailscale-ntfy` service runs the Tailscale daemon to provide secure, private networking. The `ntfy` service is configured to use Tailscale’s network stack via Docker’s `network_mode: service:tailscale` syntax. This binds ntfy’s network interface to the Tailscale container, making the HTTP API available only through your Tailscale network (or locally, if needed). +## Before you start -This architecture is ideal for self-hosters who want to send and receive notifications from anywhere without exposing the ntfy broker to the internet, maintaining both ease of access and strict privacy controls. +Create the data folders yourself and make user `1000` their owner. Docker creates missing folders as user `root`. ntfy runs as user `1000` and cannot write to folders that `root` owns. + +```bash +mkdir -p ntfy-data/etc ntfy-data/cache +sudo chown -R 1000:1000 ntfy-data +``` + +## Deviations from the standard setup + +- **Fixed user.** The `application` container runs as user and group `1000` through the `user` setting. +- **Start command.** The stack starts ntfy with the `serve` command. + +## First run + +ntfy has no login by default. Everyone who can reach the device on your Tailnet can read and publish all topics. + +1. Open the web interface and subscribe to a topic. +2. Publish a test message from a device on your Tailnet: + + ```bash + curl -d "Hello from ScaleTail" https://ntfy..ts.net/mytopic + ``` + +3. In the ntfy mobile app, set `https://ntfy..ts.net` as the server. + +## Configuration + +ntfy reads its settings from `./ntfy-data/etc/server.yml`. Create the file and restart the stack to apply it. These settings are useful behind Tailscale Serve: + +```yaml +base-url: "https://ntfy..ts.net" +behind-proxy: true +cache-file: "/var/cache/ntfy/cache.db" +``` + +- `base-url` is required for attachments and for notifications on iOS. +- `behind-proxy` makes ntfy rate-limit each visitor separately. Without it, all visitors count as one. +- `cache-file` keeps messages across restarts. Without it, ntfy keeps them in memory for 12 hours. + +To require a login, set `auth-file` and `auth-default-access: "deny-all"`. See the [ntfy configuration documentation](https://docs.ntfy.sh/config/). + +## Links + +- [ntfy documentation](https://docs.ntfy.sh/) +- [ntfy source code](https://github.com/binwiederhier/ntfy) diff --git a/services/ollama/README.md b/services/ollama/README.md index 483acc67..3004c5e4 100644 --- a/services/ollama/README.md +++ b/services/ollama/README.md @@ -1,102 +1,63 @@ -# Ollama with Tailscale Sidecar Configuration +# Ollama -This Docker Compose configuration sets up [Ollama](https://ollama.com) with Tailscale as a sidecar container to keep the API reachable securely over your Tailnet. +[Ollama](https://ollama.com) runs large language models on your own hardware, such as Llama, Mistral, and Gemma. It offers an API that is compatible with the OpenAI client format. -## Ollama +This stack runs Ollama with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Ollama](https://ollama.com) lets you run large language models (LLMs) locally — such as Llama 3, Mistral, and Gemma — with a simple API compatible with the OpenAI client format. Pairing it with Tailscale means you can access your local models from any device on your Tailnet (phone, laptop, remote machine) without exposing the API to the public internet. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | ------------------------------------------------------- | +| Web interface | None | +| API | `https://ollama..ts.net` | +| Service port | `11434` | +| Image | `ollama/ollama` | +| Data | `./ollama-data` (downloaded models, which can be large) | -In this setup, the `tailscale-ollama` service runs Tailscale, which manages secure networking for Ollama. The `app-ollama` service uses Docker's `network_mode: service:tailscale` so all traffic is routed through the Tailscale network stack. The Ollama API remains Tailnet-only by default unless you explicitly expose the port to your LAN. +## Before you start -An optional `yourNetwork` external Docker network is attached to the `tailscale` container. This allows other containers on the same host (such as Open WebUI or other LLM frontends) to reach Ollama via its Tailscale IP, keeping inter-container communication on the same overlay network. +Make sure that the disk has enough free space for the models that you want to use. -## Prerequisites +## Deviations from the standard setup -- The host user must be in the `docker` group. -- The `/dev/net/tun` device must be available on the host (standard on most Linux systems). -- Pre-create the bind-mount directories before starting the stack to avoid Docker creating root-owned folders: +- **No web interface.** Tailscale Serve publishes the API of Ollama. Use a client such as [Open WebUI](../open-webui/) for a chat interface. +- **Models stay loaded.** `OLLAMA_KEEP_ALIVE=24h` keeps a model in memory for 24 hours after its last use. +- **No authentication.** The API has no login. Everyone who can reach the device on your Tailnet can use your models. +- **Time zone.** `compose.yaml` does not pass `TZ` to the container. -```bash -mkdir -p config ts/state ollama-data -``` - -- If you use the optional `yourNetwork` network, create it first if it does not already exist: - -```bash -docker network create yourNetwork -``` - -If you don't use a shared proxy network, remove the `networks:` sections from `compose.yaml`. - -## Volumes - -| Path | Purpose | -| --------------- | ------------------------------------------------------------------ | -| `./config` | Tailscale serve config (`serve.json`) | -| `./ts/state` | Tailscale persistent state | -| `./ollama-data` | Downloaded Ollama models (can be large — ensure enough disk space) | - -## MagicDNS and HTTPS - -Tailscale Serve is pre-configured to proxy HTTPS on port 443 to Ollama's internal port 11434. To enable it: - -1. Ensure your Tailnet has MagicDNS and HTTPS certificates enabled in the [Tailscale admin console](https://login.tailscale.com/admin/dns). -2. The `serve.json` config in `compose.yaml` uses `$TS_CERT_DOMAIN` automatically — no manual editing needed. +## First run -Serve does not need `TS_ACCEPT_DNS=true`. Uncomment it only if the Ollama container itself must resolve MagicDNS names. +1. Download a model: -You can then reach Ollama at `https://ollama..ts.net`. + ```bash + docker exec app-ollama ollama pull llama3 + ``` -## Port Exposure (LAN access) +2. Send a request from a device on your Tailnet: -By default, the `ports:` section is commented out — Ollama is only accessible over your Tailnet. If you also want LAN access (e.g. from devices not on Tailscale), uncomment it in `compose.yaml`: + ```bash + curl https://ollama..ts.net/api/generate \ + -d '{"model": "llama3", "prompt": "Hello!"}' + ``` -```yaml -ports: - - 0.0.0.0:11434:11434 -``` +Other containers and devices can also use the plain HTTP port, `http://:11434`. -This is optional and not required for Tailnet-only usage. +## Configuration -## API Key (Optional) +### Local network access -Ollama supports a simple bearer token for API access. Set `OLLAMA_API_KEY` in your `.env` file to enable it. Leave it blank to allow unauthenticated access (safe when Tailnet-only). +To reach Ollama from devices that are not on your Tailnet, uncomment the `ports` block of the `tailscale` service in `compose.yaml`. It publishes port `11434` on the Docker host. -## First-time Setup +### Shared Docker network -After starting the stack, pull a model to get started: +To let other containers on the Docker host reach Ollama over a Docker network, uncomment both `networks` blocks in `compose.yaml` and replace `yourNetwork` with the name of an existing network. Create the network first if needed: ```bash -docker exec app-ollama ollama pull llama3 -``` - -You can then send requests to the API: - -```bash -curl http://:11434/api/generate \ - -d '{"model": "llama3", "prompt": "Hello!"}' -``` - -Or if using HTTPS via Tailscale Serve: - -```bash -curl https://ollama..ts.net/api/generate \ - -d '{"model": "llama3", "prompt": "Hello!"}' +docker network create yourNetwork ``` -## Files to check - -Please check the following contents for validity as some variables need to be defined upfront. - -- `.env` — Set `TS_AUTHKEY` (required). Optionally set `OLLAMA_API_KEY`. - -## Useful Links +## Links -- [Ollama official site](https://ollama.com) +- [Ollama documentation](https://docs.ollama.com/) - [Ollama model library](https://ollama.com/library) -- [Ollama GitHub](https://github.com/ollama/ollama) -- [Tailscale auth keys](https://tailscale.com/kb/1085/auth-keys) -- [Tailscale Serve docs](https://tailscale.com/kb/1312/serve) -- [Open WebUI](https://github.com/open-webui/open-webui) — a popular browser-based UI for Ollama +- [Ollama source code](https://github.com/ollama/ollama) diff --git a/services/open-webui/README.md b/services/open-webui/README.md index e62f56d4..cae5fa17 100644 --- a/services/open-webui/README.md +++ b/services/open-webui/README.md @@ -1,40 +1,46 @@ -# Open WebUI with Tailscale Sidecar Configuration +# Open WebUI -This Docker Compose configuration sets up [Open WebUI](https://openwebui.com/) with Tailscale as a sidecar container to keep the app reachable over your Tailnet. +[Open WebUI](https://openwebui.com/) is a chat interface for AI models. It works with Ollama and with every API that is compatible with OpenAI. -## Open WebUI +This stack runs Open WebUI with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Open WebUI](https://openwebui.com/) is a feature-rich, self-hosted AI platform that provides a ChatGPT-style interface for local and cloud-based AI models. It supports Ollama and any OpenAI-compatible API. Pairing it with Tailscale means your private AI interface is securely accessible from any of your devices without exposing it to the public internet. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | ------------------------------------- | +| Web interface | `https://open-webui..ts.net` | +| Service port | `8080` | +| Image | `ghcr.io/open-webui/open-webui:main` | +| Data | `./open-webui-data` | -In this setup, the `tailscale-open-webui` service runs Tailscale, which manages secure networking for Open WebUI. The `open-webui` service utilizes the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This keeps the app Tailnet-only unless you intentionally expose ports. +## Before you start -## What to document for users +Set these values in `.env`: -- **Prerequisites**: Docker and Docker Compose installed. No special group membership, GPU, or devices required for CPU-only inference. A Tailscale account with an auth key from . -- **Volumes**: Pre-create `./open-webui-data` before deploying to avoid Docker creating a root-owned directory: `mkdir -p ./open-webui-data ./config ./ts/state` -- **MagicDNS/Serve**: Enable MagicDNS and HTTPS in your Tailscale admin console before deploying. The serve config proxies to port `8080` — this is hardcoded in the `configs` block and does not consume `.env` values. Uncomment `TS_ACCEPT_DNS=true` in `compose.yaml` only if Open WebUI itself must resolve MagicDNS names, such as an Ollama instance addressed by its Tailnet name. -- **Ollama**: Set `OLLAMA_BASE_URL` in `.env` to point at your Ollama instance. Options: - - Same Docker host: `http://host.docker.internal:11434` - - LAN machine: `http://:11434` (use the private IP of the machine running Ollama) - - Another Tailnet device: `http://100.x.x.x:11434` - - Leave blank to configure a different provider (e.g. OpenAI) via the UI after first launch. -- **Ports**: The `0.0.0.0:${SERVICEPORT}:${SERVICEPORT}` mapping is commented out by default. Uncomment only if LAN access is required alongside Tailnet access. -- **Gotchas**: - - Create your admin account immediately after first launch — Open WebUI is open to registration until the first user is created. - - Open WebUI requires WebSocket support — ensure nothing in your network path blocks WebSocket connections. - - After adding new models to Ollama, refresh the model list in Open WebUI via **Settings → Connections**. +- **`WEBUI_SECRET_KEY`.** A long random value that Open WebUI uses to sign the login tokens. +- **`OLLAMA_BASE_URL`.** The address of your Ollama instance: + - On the Docker host: `http://host.docker.internal:11434` + - On a machine in your local network: `http://:11434` + - On another Tailnet device: `http://:11434` + - Leave it empty to add another provider, such as OpenAI, in the web interface later. -## Files to check +## Deviations from the standard setup -Please check the following contents for validity as some variables need to be defined upfront. +None. -- `.env` // Main variables: `TS_AUTHKEY`, `SERVICE`, `IMAGE_URL`, `OLLAMA_BASE_URL`, `WEBUI_SECRET_KEY` +## First run -## Resources +Open the web interface and create your account right after the first start. The first account becomes the administrator, and until then everyone who can reach the device on your Tailnet can register it. -- [Open WebUI Documentation](https://docs.openwebui.com/) -- [Open WebUI GitHub](https://github.com/open-webui/open-webui) -- [Tailscale Serve docs](https://tailscale.com/kb/1242/tailscale-serve) -- [Tailscale Docker guide](https://tailscale.com/blog/docker-tailscale-guide) +After you add models to Ollama, refresh the model list in Open WebUI under **Settings** > **Connections**. + +## Configuration + +- **MagicDNS.** Uncomment `TS_ACCEPT_DNS=true` in `compose.yaml` only if Open WebUI must resolve MagicDNS names, such as an Ollama instance that you address by its Tailnet name. +- **WebSockets.** Open WebUI needs WebSocket connections. Make sure that nothing between your browser and the device blocks them. + +## Links + +- [Open WebUI documentation](https://docs.openwebui.com/) +- [Open WebUI source code](https://github.com/open-webui/open-webui) +- [Ollama stack in this repository](../ollama/) diff --git a/services/paperless/README.md b/services/paperless/README.md index adc2d7b5..db90c2f1 100644 --- a/services/paperless/README.md +++ b/services/paperless/README.md @@ -1,13 +1,46 @@ -# Paperless-ngx with Tailscale Sidecar Configuration +# Paperless-ngx -This Docker Compose configuration sets up [Paperless-ngx](https://docs.paperless-ngx.com/) with Tailscale as a sidecar container to securely deliver push notifications over a private Tailscale network. By integrating Tailscale in a sidecar configuration, you enhance the privacy and security of your ntfy instance, ensuring it is only accessible within your Tailscale network. +[Paperless-ngx](https://docs.paperless-ngx.com/) is a document management system. It turns your scans and files into a searchable archive with text recognition, tags, and correspondents. -## Paperless-ngx +This stack runs Paperless-ngx with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Paperless-ngx](https://docs.paperless-ngx.com) is a community-supported open-source document management system that transforms your physical documents into a searchable online archive so you can keep, well, less paper. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | -------------------------------------------------------------------------------- | +| Web interface | `https://paperless..ts.net` | +| Service port | `80` | +| Images | `ghcr.io/paperless-ngx/paperless-ngx` | +| | `docker.io/library/postgres` | +| | `docker.io/library/redis` | +| Data | `./paperless-data/consume` (inbox: Paperless-ngx imports files from this folder) | +| | `./paperless-data/media` (your documents) | +| | `./paperless-data/data` (search index and logs) | +| | `./paperless-data/export` (exports) | +| | `./paperless-data/pgdata` (PostgreSQL database) | +| | `./paperless-data/redisdata` (Redis data) | -In this setup, the `tailscale-paperless` service runs the Tailscale daemon to provide secure, private networking. The `paperless` service is configured to use Tailscale’s network stack via Docker’s `network_mode: service:tailscale` syntax. This binds Paperless network interface to the Tailscale container, making the service available only through your Tailscale network (or locally, if needed). +## Before you start -This architecture is ideal for self-hosters who want to send and receive notifications from anywhere without exposing Paperless-ngx to the internet, maintaining both ease of access and strict privacy controls. +Change these values in `.env`: + +- **`PAPERLESS_SECRET_KEY`.** A long random value. Paperless-ngx uses it to sign session tokens. +- **`PAPERLESS_ADMIN_USER` and `PAPERLESS_ADMIN_PASSWORD`.** The administrator account that Paperless-ngx creates at the first start. The defaults are `admin` and `changeme`. +- **`POSTGRES_PASSWORD`.** The password of the database. +- **`PAPERLESS_OCR_LANGUAGE`.** The language of your documents as a three-letter code, such as `eng` or `nld`. +- **`PAPERLESS_TIME_ZONE`.** Your time zone. + +## Deviations from the standard setup + +- **Extra containers.** The stack runs `db` (PostgreSQL) and `broker` (Redis). They use the default Compose network, and Paperless-ngx reaches them by their service name through Docker's DNS. Keep `TS_ACCEPT_DNS` disabled, because MagicDNS cannot resolve these names. +- **Service port.** `PAPERLESS_PORT=80` makes Paperless-ngx listen on port `80` and not on its default port `8000`. +- **HTTPS behind Tailscale Serve.** `PAPERLESS_PROXY_SSL_HEADER` tells Paperless-ngx that Tailscale Serve provides HTTPS. + +## First run + +Open the web interface and log in with the administrator account from `.env`. To import documents, upload them in the web interface or put them in `./paperless-data/consume`. + +## Links + +- [Paperless-ngx documentation](https://docs.paperless-ngx.com/) +- [Paperless-ngx source code](https://github.com/paperless-ngx/paperless-ngx) diff --git a/services/picard/README.md b/services/picard/README.md index 01c99d95..37a3f353 100644 --- a/services/picard/README.md +++ b/services/picard/README.md @@ -1,40 +1,32 @@ -# MusicBrainz Picard with Tailscale Sidecar Configuration +# MusicBrainz Picard -This Docker Compose setup deploys **MusicBrainz Picard** alongside a **Tailscale sidecar container**, allowing secure access to your self-hosted music tagging and metadata management environment over your private **Tailscale network**. With this setup, Picard remains **private and reachable only from trusted devices within your Tailnet**, ensuring your media metadata library stays secure and isolated from the public internet. +[MusicBrainz Picard](https://picard.musicbrainz.org/) is the tag editor of MusicBrainz. It identifies your music files, also by their audio fingerprint, and writes the correct tags and cover art. This stack runs the desktop application in a container and shows it in your browser. -## MusicBrainz Picard +This stack runs MusicBrainz Picard with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[**MusicBrainz Picard**](https://picard.musicbrainz.org/) is the official cross-platform tag editor from [MusicBrainz](https://musicbrainz.org/). It uses the community-maintained MusicBrainz database to identify, tag, and organize your music files with accurate and rich metadata — including artist information, album art, release data, and more. +## At a glance -Picard supports a wide range of audio formats and integrates powerful plugins to streamline batch processing, fingerprinting (via AcoustID), and custom tagging workflows. +| Item | Value | +| ------------- | --------------------------------------------------------------- | +| Web interface | `https://picard..ts.net` | +| Service port | `5800` | +| Image | `mikenye/picard` | +| Data | `./picard-data/config` (Picard settings) | +| | `./picard-data/music` (your music, `/storage` in the container) | -## Key Features +## Before you start -- 🎵 **Accurate Tagging** – Automatically identify and tag music files using MusicBrainz metadata. -- 🧠 **AcoustID Matching** – Use audio fingerprints to detect and tag tracks even without metadata. -- 🖼️ **Album Art Integration** – Fetch and embed high-quality cover art automatically. -- ⚙️ **Plugin Support** – Extend functionality with community or custom plugins. -- 📁 **Batch Processing** – Organize entire libraries with flexible renaming and folder rules. -- 🐳 **Docker-Ready** – Simple to deploy and run in containers. -- 🔐 **Private Access via Tailscale** – Keep your tagging environment accessible only on your Tailnet. -- 📦 **Open Source** – Actively maintained and community-driven. +Point the `/storage` volume in `compose.yaml` at the folder with your music. Picard changes and renames the files in that folder. User and group `1000` need write access to it. -## Why Self-Host? +## Deviations from the standard setup -When you manage large local music libraries, you may prefer **full privacy and control** over which metadata services your files connect to. Self-hosting Picard behind Tailscale offers: +- **User and group.** The image uses `USER_ID` and `GROUP_ID` for the user that runs Picard, which `compose.yaml` sets to `1000`. -- No exposure of ports to the public internet. -- Private access to your tagging environment from any authorized Tailscale device. -- A streamlined tagging workflow fully contained within your home media infrastructure. +## First run -With this setup, your tagging process is secured and contained — perfect for privacy-conscious audiophiles and homelab enthusiasts. +Open the web interface. It shows the Picard window and has no login. Add files from `/storage` to start tagging. -## Configuration Overview +## Links -In this deployment, a **Tailscale sidecar container** (for example `tailscale-picard`) connects your Picard instance to your private Tailnet. The main `picard` container uses: - -```plain -network_mode: service:tailscale -``` - -This means all Picard traffic — web interface, plugin updates, and library calls — travels securely through Tailscale. +- [MusicBrainz Picard documentation](https://picard-docs.musicbrainz.org/) +- [mikenye/picard image](https://github.com/mikenye/docker-picard) diff --git a/services/pihole/README.md b/services/pihole/README.md index d2292210..645a2e88 100644 --- a/services/pihole/README.md +++ b/services/pihole/README.md @@ -1,62 +1,71 @@ -# Pi-hole with Tailscale Sidecar Configuration +# Pi-hole -This Docker Compose configuration sets up [Pi-hole](https://github.com/pi-hole/pi-hole) with Tailscale as a sidecar container to securely manage and access your network-wide ad blocker over a private Tailscale network. By using Tailscale in a sidecar configuration, you can enhance the security and privacy of your Pi-hole instance, ensuring that it is only accessible within your Tailscale network. +[Pi-hole](https://github.com/pi-hole/pi-hole) is a DNS server that blocks advertisements and trackers for every device that uses it. -## Pi-hole +This stack runs Pi-hole with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Pi-hole](https://github.com/pi-hole/pi-hole) is a network-wide ad blocker that acts as a DNS sinkhole, filtering out ads and trackers across all devices on your local network. It improves your browsing experience by blocking unwanted content before it even reaches your device. This configuration leverages Tailscale to securely connect to your Pi-hole instance, ensuring that your DNS requests and administrative interface are protected from unauthorized access. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | --------------------------------------------------------------- | +| Web interface | `https://pihole..ts.net/admin` | +| Service port | `80` | +| DNS | Port `53` (TCP and UDP) on the Tailscale IP address of `pihole` | +| Image | `pihole/pihole` | +| Data | `./pihole-data/etc-pihole` (settings and databases) | +| | `./pihole-data/etc-dnsmasq.d` (custom dnsmasq configuration) | -In this setup, the `tailscale-pihole` service runs Tailscale, which manages secure networking for the Pi-hole service. The `pihole` service uses the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This setup ensures that Pi-hole’s DNS service and web interface are only accessible through the Tailscale network (or locally, if preferred), providing an extra layer of security and privacy for your network-wide ad blocker. +## Before you start -## Binding to your local host machine? Port 53 - DNSStubListener +Nothing beyond the [Quick Start](../../README.md#quick-start). -In Debian (e.g. Ubuntu Server 22.04.x / 24.04.x) systems, particularly when using systemd-resolved for DNS resolution, a DNS stub listener is employed by default to provide local DNS resolution through the loopback address (localhost). This stub listener binds to port 53 on the local interface 127.0.0.53, allowing local applications to send DNS queries to this address for resolution. +## Deviations from the standard setup -### What is DNSStubListener? +- **The web interface is at `/admin`.** Pi-hole serves its web interface under this path and answers a request for `/` with error `403`. +- **DNS does not use Tailscale Serve.** Serve only handles the web interface. Pi-hole listens for DNS queries on port `53` of the Tailscale IP address of the device. +- **No DHCP server.** The stack does not publish port `67` and does not give the application the `NET_ADMIN` capability, which the Pi-hole DHCP server needs. -`DNSStubListener` is a configuration option in the `/etc/systemd/resolved.conf` file that controls whether the `systemd-resolved` service will listen for DNS queries on the loopback address (127.0.0.53) over port 53. +## First run -- **DNSStubListener=yes**: When this option is enabled, `systemd-resolved` binds to `127.0.0.53:53`. This allows the system to use `systemd-resolved` as a local DNS resolver for local DNS queries. +1. Pi-hole generates a random password for the web interface at the first start. Find it in the log: -- **DNSStubListener=no**: Disabling the stub listener prevents `systemd-resolved` from binding to port 53 on the local interface, freeing up this port for other DNS services or applications that require direct control over port 53. + ```bash + docker logs app-pihole 2>&1 | grep "random password" + ``` -### Why Change `DNSStubListener` to `no`? + To set your own password, run: -In certain scenarios, such as when running a local DNS server (e.g., AdguardHome, PiHole, BIND, Unbound, or Dnsmasq) or any other application that requires exclusive access to port 53 on all interfaces, `systemd-resolved`'s binding to the local DNS port can cause conflicts. For example, if you plan to run your own DNS server on the same machine, that service needs to bind to port 53 globally, including the loopback interface. With `systemd-resolved` already occupying this port, the new DNS service would fail to start or function properly. + ```bash + docker exec app-pihole pihole setpassword 'your-password' + ``` -To resolve this issue, you need to disable `systemd-resolved` from binding to port 53 by setting `DNSStubListener=no` in the `/etc/systemd/resolved.conf` file. +2. Open the web interface and log in. -### Steps to Free Up Port 53 +## Configuration -1. **Open the configuration file**: +### Use Pi-hole as the DNS server of your Tailnet - ```bash - sudo nano /etc/systemd/resolved.conf - ``` +Follow the [Pi-hole guide from Tailscale](https://tailscale.com/kb/1114/pi-hole). In short: -2. **Modify the `DNSStubListener` setting**: +1. In the Pi-hole web interface, go to **Settings** > **DNS**, switch from **Basic** to **Expert**, and select **Permit all origins** under the interface settings. Tailnet devices have `100.x.y.z` addresses, which Pi-hole does not treat as local. +2. In the Tailscale admin console, open the **DNS** page. Add the Tailscale IP address of the `pihole` device as a custom nameserver and enable **Override DNS servers**. - Find the line containing `#DNSStubListener=yes` (it might be commented out by default) and change it to: +### Offer DNS to your local network - ```bash - DNSStubListener=no - ``` - -3. **Restart the `systemd-resolved` service**: - After saving the changes, restart the service for the changes to take effect: +Uncomment the `ports:` line of the `tailscale` service in `compose.yaml` and add port `53` below it: - ```bash - sudo systemctl restart systemd-resolved - ``` +```yaml + ports: + - 0.0.0.0:53:53/tcp + - 0.0.0.0:53:53/udp +``` -4. **Verify Port 53 is Free**: +Pi-hole also needs the **Permit all origins** setting for this, because the queries arrive through Docker's bridge network. - You can check that port 53 is no longer bound by `systemd-resolved` by running: +On a host that runs `systemd-resolved`, port `53` is already in use. See [Free up port 53 on the Docker host](../../documentation/free-up-port-53.md). - ```bash - sudo netstat -tuln | grep :53 - ``` +## Links -If the configuration was successful, no process should be listed as using port 53 on the loopback interface. +- [Pi-hole documentation](https://docs.pi-hole.net/) +- [Pi-hole Docker image](https://github.com/pi-hole/docker-pi-hole) +- [Pi-hole source code](https://github.com/pi-hole/pi-hole) diff --git a/services/pingvin-share/README.md b/services/pingvin-share/README.md index d9c2729f..a6446066 100644 --- a/services/pingvin-share/README.md +++ b/services/pingvin-share/README.md @@ -1,13 +1,33 @@ -# Pingvin Share with Tailscale Sidecar Configuration +# Pingvin Share -**PLEASE NOTE** As per June 29, 2025 pingvin-share **has been archived** by the developer. +[Pingvin Share](https://github.com/stonith404/pingvin-share) is a file sharing platform. You upload files and share them with a link that can expire. -This Docker Compose configuration sets up [Pingvin Share](https://github.com/stonith404/pingvin-share) with Tailscale as a sidecar container to securely share files over a private Tailscale network. By using Tailscale in a sidecar configuration, you can ensure your file-sharing instance is accessible only within your Tailscale network, providing enhanced security and privacy. +Upstream archived the project on June 29, 2025, so it gets no further updates. Its author points to the maintained fork Pingvin Share X. -## Pingvin Share +This stack runs Pingvin Share with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Pingvin Share](https://github.com/stonith404/pingvin-share) is a simple, open-source file-sharing application designed to make sharing files quick, easy, and efficient. It supports drag-and-drop uploads, expiring links, and a user-friendly web interface. With this setup, Tailscale ensures that your Pingvin Share instance remains secure and private, limiting access to only authorized devices on your Tailscale network. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | --------------------------------------------------------- | +| Web interface | `https://pingvin-share..ts.net` | +| Service port | `3000` | +| Image | `stonith404/pingvin-share` | +| Data | `./pingvin-share-data/data` (database and uploaded files) | +| | `./pingvin-share-data/images` (logo and icons) | -In this setup, the `tailscale-pingvin` service runs Tailscale, which manages secure networking for the Pingvin Share service. The `pingvin-share` service uses the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This ensures that Pingvin Share’s web interface and file-sharing capabilities are only accessible through the Tailscale network (or locally, if preferred), providing an extra layer of security and privacy for your self-hosted file-sharing needs. +## Before you start + +Nothing beyond the [Quick Start](../../README.md#quick-start). + +## Deviations from the standard setup + +None. + +## First run + +Open the web interface and sign up. The first account becomes the administrator. Registration stays open for everyone who can reach the device on your Tailnet, until you disable it in the administration settings. + +## Links + +- [Pingvin Share source code](https://github.com/stonith404/pingvin-share) diff --git a/services/plex/README.md b/services/plex/README.md index efc54976..08ed0027 100644 --- a/services/plex/README.md +++ b/services/plex/README.md @@ -1,11 +1,35 @@ -# Plex with Tailscale Sidecar Configuration +# Plex -This Docker Compose configuration sets up [Plex Media Server](https://hub.docker.com/r/linuxserver/plex) with Tailscale as a sidecar container to securely manage and stream your media over a private Tailscale network. By using Tailscale in a sidecar configuration, you can enhance the security and privacy of your media server, ensuring that it is only accessible within your Tailscale network. +[Plex Media Server](https://www.plex.tv/) organises your movies, series, and music and streams them to the Plex apps on your devices. -## Plex Media Server +This stack runs Plex with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Plex Media Server](https://hub.docker.com/r/linuxserver/plex) is a versatile platform for organizing and streaming your personal media collection, including movies, TV shows, music, and photos. Plex makes it easy to access your media from any device, both locally and remotely, with a user-friendly interface and extensive device support. This configuration leverages Tailscale to securely connect to your Plex server, protecting your media streams from unauthorized access. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | ---------------------------------------------------- | +| Web interface | `https://plex..ts.net/web` | +| Service port | `32400` | +| Image | `lscr.io/linuxserver/plex` | +| Data | `./plex-data/config` (library database and settings) | +| | `./plex-data/media/movies` (movie library) | +| | `./plex-data/media/tvseries` (series library) | -In this setup, the `tailscale-plex` service runs Tailscale, which manages secure networking for the Plex Media Server. The `plex` service utilizes the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This setup ensures that Plex's media streaming service is only accessible through the Tailscale network (or locally, if preferred), providing an extra layer of security and privacy for your media server. +## Before you start + +- **Claim token.** Get a token at and add it to `PLEX_CLAIM=` in `compose.yaml`. The token expires after four minutes, so start the stack right away. Without it, the server starts unclaimed and is not linked to your Plex account. +- **Media folders.** Point the `/movies` and `/tv` volumes in `compose.yaml` at your own media folders. Otherwise the stack starts with empty folders in `./plex-data/media`. + +## Deviations from the standard setup + +- **Web interface path.** The web interface is at `/web`. The root path `/` answers with server information in XML. +- **No host networking.** The image documentation recommends host networking. This stack uses the network of the `tailscale` container and publishes no ports, so devices that are not on your Tailnet cannot reach Plex. + +## First run + +Open the web interface and sign in with your Plex account. Then add your libraries with `/movies` and `/tv` as folders. + +## Links + +- [Plex support](https://support.plex.tv/) +- [LinuxServer.io image documentation](https://docs.linuxserver.io/images/docker-plex/) diff --git a/services/pocket-id/README.md b/services/pocket-id/README.md index e892adff..b437144c 100644 --- a/services/pocket-id/README.md +++ b/services/pocket-id/README.md @@ -1,50 +1,44 @@ -# Pocket ID with Tailscale Sidecar Configuration +# Pocket ID -This Docker Compose configuration sets up [Pocket ID](https://pocket-id.org/) with Tailscale as a sidecar container, enabling secure access to your self-hosted identity provider over a private Tailscale network. With this setup, your Pocket ID instance remains private and accessible only from devices on your Tailnet, over HTTPS. +[Pocket ID](https://pocket-id.org/) is a simple OpenID Connect (OIDC) provider. Users sign in to your services with passkeys instead of passwords, which gives the services on your Tailnet a single sign-on. -## Pocket ID +This stack runs Pocket ID with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Pocket ID](https://github.com/pocket-id/pocket-id) is a simple, self-hosted OpenID Connect (OIDC) provider that lets users sign in to your services with passkeys instead of passwords. It is a lightweight alternative to larger identity providers such as Keycloak, and gives the other services on your Tailnet a single sign-on. +## At a glance -## Key Features +| Item | Value | +| ------------- | ------------------------------------ | +| Web interface | `https://pocket-id..ts.net` | +| Service port | `1411` | +| Image | `ghcr.io/pocket-id/pocket-id:v2` | +| Data | `./pocket-id-data` | -- **Passkey-Only Sign-In** – Users authenticate with passkeys; there are no passwords to manage. -- **OIDC Provider** – Add single sign-on to any application that supports OpenID Connect. -- **Security Key Support** – Physical security keys, such as a YubiKey, work as passkeys. -- **Simple to Run** – One container and a SQLite database by default. -- **Self-Hosted** – Users, clients, and signing keys stay on your own hardware. -- **Private by Default with Tailscale** – No public exposure, no reverse proxies or port forwarding, and HTTPS handled by Tailscale Serve. +## Before you start -## Configuration Overview +- **Enable HTTPS certificates.** HTTPS certificates must be [enabled for your Tailnet](https://console.tailscale.com/admin/dns) (**DNS** > **HTTPS Certificates**). Passkeys only work over HTTPS. +- **Set `APP_URL` in `.env`.** Use the address of the web interface, `https://pocket-id..ts.net`. Pocket ID uses it for its OIDC issuer, its endpoints, and passkeys, and it does not start with the sample value. +- **Set `ENCRYPTION_KEY` in `.env`.** Generate the key with `openssl rand -base64 32`. -In this setup, the `tailscale` service (container `tailscale-pocket-id`) runs Tailscale and joins your Tailnet as the host `pocket-id`. The `application` service (container `app-pocket-id`) uses the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. Tailscale Serve terminates HTTPS on port 443 and proxies to Pocket ID on `127.0.0.1:1411` inside that shared namespace. This keeps the app Tailnet-only unless you intentionally expose ports. +## Deviations from the standard setup -## Prerequisites +- **The container reads the whole `.env` file.** The `application` container loads `.env` through `env_file`. Every variable in that file, including `TS_AUTHKEY`, is therefore present in its environment. +- **Trusted proxy.** `TRUST_PROXY=true` in `.env` makes Pocket ID accept the client address that Tailscale Serve forwards. +- **User and group.** `PUID` and `PGID` come from `.env`. -- HTTPS certificates [enabled for your Tailnet](https://console.tailscale.com/admin/dns) (**DNS → HTTPS Certificates**). Pocket ID requires a secure context, so passkeys do not work without HTTPS. +## First run -## Files to check +Open `https://pocket-id..ts.net/setup` to create the administrator account and its first passkey. -Please verify the following files and variables before deploying: +## Configuration -- `.env` — set `TS_AUTHKEY`, `APP_URL`, and `ENCRYPTION_KEY`. Generate the key with `openssl rand -base64 32`. -- `compose.yaml` — confirm the volume paths and the `Proxy` port in the `ts-serve` config. +- **`APP_URL` must match `SERVICE`.** Tailscale Serve publishes Pocket ID on the device name, which comes from `SERVICE`. `APP_URL` does not change that address. When the two differ, Pocket ID answers on the `SERVICE` name while it sends clients to an address that does not exist, and passkey sign-in fails. +- **Use another name.** To serve Pocket ID at, for example, `https://id..ts.net`, set `SERVICE=id` and set `APP_URL` to that address. Choose the name before users register passkeys, because a passkey is bound to the host name in `APP_URL`. +- **Rename an existing deployment.** The data folder is `./-data`, so a new `SERVICE` value starts Pocket ID with an empty folder. Run `docker compose down`, change `SERVICE` and `APP_URL`, rename the folder (for example `mv pocket-id-data id-data`), and run `docker compose up -d`. Tailscale renames the existing device from the stored state, so you need no new auth key. A device that you renamed by hand in the admin console keeps that name. +- **Custom domains.** Tailscale Serve only serves the `ts.net` name of the device. A custom domain in `APP_URL` needs your own DNS and reverse proxy, which this stack does not include. +- **Local network access.** The `ports` block stays commented out. If you enable it, the stack publishes plain HTTP on the Docker host, where passkeys do not work. -## Usage Notes +## Links -- **`APP_URL` must match `SERVICE`.** Tailscale Serve publishes Pocket ID on the machine name, which comes from `SERVICE`, so the app is reached at `https://..ts.net`. `APP_URL` does not change that address. It only tells Pocket ID which URL to use for its OIDC issuer, its endpoints, and passkeys. When the two differ, the app answers on the `SERVICE` name while clients are sent to an address that does not exist, and passkey sign-in fails. -- **Using another name.** To serve Pocket ID at, for example, `https://id..ts.net`, set `SERVICE=id` and set `APP_URL` to that URL. Choose the name before users register passkeys, because passkeys are bound to the hostname in `APP_URL`. -- **Renaming an existing deployment.** The data folder is `./${SERVICE}-data`, so a new `SERVICE` value starts Pocket ID with an empty folder. Run `docker compose down`, change `SERVICE` and `APP_URL`, rename the folder (for example `mv pocket-id-data id-data`), and run `docker compose up -d`. Tailscale renames the existing machine from the stored state, so no new auth key is needed. A machine that you renamed by hand in the admin console keeps that name. -- **Custom domains.** Tailscale Serve only serves the machine's `ts.net` name. A custom domain in `APP_URL` needs your own DNS and reverse proxy, which this stack does not include. -- **First run.** Open `https://pocket-id..ts.net/setup` to create the admin account and its first passkey. -- **Health check.** The image defines its own health check (`/app/pocket-id healthcheck`), so `compose.yaml` does not override it. -- **Ports.** The `ports` block stays commented out; the Tailnet is the only way in. Uncommenting it publishes plain HTTP on the host, where passkeys do not work. - -## References - -- [Pocket ID website](https://pocket-id.org/) -- [Pocket ID on GitHub](https://github.com/pocket-id/pocket-id) - [Pocket ID installation](https://pocket-id.org/docs/setup/installation) - [Pocket ID environment variables](https://pocket-id.org/docs/configuration/environment-variables) -- [Tailscale Serve documentation](https://tailscale.com/kb/1242/tailscale-serve) -- [Tailscale auth keys](https://tailscale.com/kb/1085/auth-keys) +- [Pocket ID source code](https://github.com/pocket-id/pocket-id) diff --git a/services/portainer/README.md b/services/portainer/README.md index 893de772..5ee72395 100644 --- a/services/portainer/README.md +++ b/services/portainer/README.md @@ -1,11 +1,38 @@ -# Portainer with Tailscale Sidecar Configuration +# Portainer -This Docker Compose configuration sets up [Portainer](https://github.com/portainer/portainer) with Tailscale as a sidecar container to securely manage and monitor your Docker environments over a private Tailscale network. By using Tailscale in a sidecar configuration, you can enhance the security and privacy of your Portainer instance, ensuring that it is only accessible within your Tailscale network. +[Portainer](https://www.portainer.io/) is a web interface to manage Docker. You start, stop, inspect, and update the containers, images, volumes, and networks of the Docker host. -## Portainer +This stack runs Portainer with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Portainer](https://github.com/portainer/portainer) is an open-source management tool that provides a simple and easy-to-use interface for managing Docker environments. Whether you are deploying containers, managing networks, or monitoring your Docker services, Portainer offers a comprehensive solution for managing your containerized applications. This configuration leverages Tailscale to securely connect to your Portainer instance, protecting your Docker management interface from unauthorized access. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | ------------------------------------ | +| Web interface | `https://portainer..ts.net` | +| Service port | `9000` | +| Image | `portainer/portainer-ce` | +| Data | `./portainer-data/portainer_data` | -In this setup, the `tailscale-portainer` service runs Tailscale, which manages secure networking for the Portainer service. The `portainer` service uses the Tailscale network stack via Docker’s `network_mode: service:tailscale` configuration. This setup ensures that Portainer’s management interface is only accessible through the Tailscale network (or locally, if preferred), providing an extra layer of security and privacy for managing your Docker environments. +## Before you start + +Nothing beyond the [Quick Start](../../README.md#quick-start). + +## Deviations from the standard setup + +- **Docker socket.** Portainer mounts `/var/run/docker.sock` with write access, which it needs to manage Docker. Everyone who can log in to Portainer has full control over the Docker host. + +## First run + +1. Portainer prints a setup token to the log at the first start: + + ```bash + docker logs app-portainer 2>&1 | grep setup_token + ``` + +2. Open the web interface. Enter the setup token and create the administrator account. The password must have at least 12 characters. +3. Portainer then manages the Docker host through the mounted Docker socket. + +## Links + +- [Portainer documentation](https://docs.portainer.io/) +- [Portainer source code](https://github.com/portainer/portainer) diff --git a/services/portracker/README.md b/services/portracker/README.md index 257d9589..8aeaad57 100644 --- a/services/portracker/README.md +++ b/services/portracker/README.md @@ -1,22 +1,31 @@ -# Portracker with Tailscale Sidecar Configuration +# Portracker -This Docker Compose configuration sets up [Portracker](https://github.com/mostafa-wahied/portracker) with Tailscale as a sidecar container to securely access your lightweight port monitoring and tracking tool over a private Tailscale network. By using Tailscale in a sidecar configuration, you can enhance the security and accessibility of your Portracker instance, ensuring it is only available within your Tailscale network. +[Portracker](https://github.com/mostafa-wahied/portracker) discovers the services on your systems and shows which ports they use, so that you have a live map of your ports. -## Portracker +This stack runs Portracker with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Portracker](https://github.com/mostafa-wahied/portracker) is a simple, self-hosted port monitoring tool that helps you keep track of open ports on your servers. It provides a web interface for viewing, searching, and exporting port information, making it easy to audit and manage your network exposure. Portracker is lightweight, easy to deploy, and requires minimal configuration. With this setup, Portracker is exposed only to your Tailscale network, providing secure, peer-to-peer access from your devices. +## At a glance -**Key Features:** +| Item | Value | +| ------------- | ------------------------------------- | +| Web interface | `https://portracker..ts.net` | +| Service port | `4999` | +| Image | `mostafawahied/portracker` | +| Data | `./portracker-data/data` | -- 🔍 Real-time port monitoring and listing -- 📊 Export port data to CSV for audits -- 🖥️ Simple web interface for browsing and searching -- 🛡️ Helps identify open ports and potential vulnerabilities -- ⚡ Lightweight and fast deployment -- 🔧 Minimal configuration required +## Before you start -With Tailscale in place, all of these features are securely tunneled through your private mesh network—no need to expose ports to the public internet. +Nothing beyond the [Quick Start](../../README.md#quick-start). -## Configuration Overview +## Deviations from the standard setup -In this setup, the `tailscale-portracker` service runs Tailscale, which handles the secure networking layer. The `portracker` service uses Docker’s `network_mode: service:tailscale` setting to share the network stack of the Tailscale container. This means the Portracker web interface and all monitoring functionality are only accessible via the Tailscale network (or locally if preferred), adding a strong privacy layer to your self-hosted port tracker. +- **Docker socket.** Portracker mounts `/var/run/docker.sock` read-only to discover the containers on the Docker host. +- **No access to host processes.** Upstream also uses `pid: host` and the `SYS_PTRACE` and `SYS_ADMIN` capabilities to discover the ports of processes on the host. This stack does not set them. See the upstream documentation if you need these ports. + +## First run + +Portracker has no login by default. Open the web interface. To require a login, set `ENABLE_AUTH=true` in the `environment` block of `compose.yaml`. Portracker then shows a setup wizard for the administrator account. + +## Links + +- [Portracker documentation and source code](https://github.com/mostafa-wahied/portracker) diff --git a/services/posterizarr/README.md b/services/posterizarr/README.md index d59a1d62..639cb830 100644 --- a/services/posterizarr/README.md +++ b/services/posterizarr/README.md @@ -1,48 +1,39 @@ -# Posterizarr with Tailscale Sidecar Configuration +# Posterizarr -This Docker Compose configuration sets up **Posterizarr** with a Tailscale sidecar container, enabling secure and private access to your automated poster and artwork management service for *Radarr* and *Sonarr*. With this setup, Posterizarr is **only accessible from within your Tailscale network**, keeping your media automation environment clean, private, and secure. +[Posterizarr](https://github.com/fscorrupt/Posterizarr) creates posters, backgrounds, and title cards for your media library in one style. It reads your library from Plex, Jellyfin, or Emby and downloads the artwork from several sources. -## Posterizarr +This stack runs Posterizarr with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[**Posterizarr**](https://github.com/fscorrupt/Posterizarr) is a companion tool for Radarr and Sonarr that **automatically manages posters, backgrounds, and other artwork** based on predefined rules. It ensures a consistent visual style across your media library by automatically applying selected poster sources, resolutions, languages, and artwork types. +## At a glance -## Key Features +| Item | Value | +| ------------- | --------------------------------------------------------- | +| Web interface | `https://posterizarr..ts.net` | +| Service port | `8000` | +| Image | `ghcr.io/fscorrupt/posterizarr` | +| Data | `./posterizarr-data/config` (configuration and database) | +| | `./posterizarr-data/assets` (created artwork) | +| | `./posterizarr-data/assetsbackup` (backup of the artwork) | +| | `./posterizarr-data/manualassets` (your own artwork) | -* 🖼 **Automated Poster Management** – Automatically updates posters and artwork for movies and series. -* 🎨 **Consistent Library Aesthetics** – Enforce a uniform look across Radarr and Sonarr. -* 🔧 **Rule-Based Configuration** – Define poster sources, languages, resolutions, and priorities. -* 🔄 **Scheduled Syncing** – Periodically checks and updates artwork automatically. -* 📡 **Radarr & Sonarr Integration** – Uses official APIs to manage media artwork. -* 🐳 **Docker-Native** – Lightweight container designed for easy self-hosting. -* 🧩 **Multi-Instance Support** – Manage artwork across multiple Radarr/Sonarr instances. +## Before you start -## Why Self-Host? +Create the data folders yourself and make user `1000` their owner. Docker creates missing folders as user `root`. The stack runs Posterizarr as user and group `1000`, and it then fails with `Permission denied: '/config/database'`. -Posterizarr requires **API access to Radarr and Sonarr**, which exposes metadata and library structure details. Self-hosting Posterizarr behind Tailscale ensures: - -* Radarr and Sonarr APIs are not publicly exposed -* Poster and artwork management stays inside your private network -* Secure remote management without opening firewall ports - -This approach is ideal for homelabs, media servers, and multi-location setups where privacy and security matter. - -## Configuration Overview - -In this deployment, a **Tailscale sidecar container** (for example, `tailscale-posterizarr`) runs the Tailscale client and connects to your private Tailscale network. The Posterizarr service uses: - -```plain -network_mode: service:tailscale +```bash +mkdir -p posterizarr-data/config posterizarr-data/assets posterizarr-data/assetsbackup posterizarr-data/manualassets +sudo chown -R 1000:1000 posterizarr-data ``` -This configuration ensures that **all Posterizarr traffic is routed exclusively through the Tailscale interface**, allowing it to securely communicate with Radarr and Sonarr instances over your private network. No ports are exposed to the public Internet, and the service remains fully isolated. +## Deviations from the standard setup -With this setup, Posterizarr can reliably enforce consistent artwork standards across your media library — securely, privately, and automatically. +- **Fixed user.** The `application` container runs as user and group `1000` through the `user` setting. +- **No scheduled runs.** `RUN_TIME=disabled` turns off the schedule of the container. You start runs from the web interface. -## Volume Permissions +## First run -The Compose file runs Posterizarr as UID/GID `1000`. Docker creates missing bind-mount directories as `root:root`, and Posterizarr then fails with `Permission denied: '/config/database'`. Create the data directories before the first start: +Posterizarr has no login by default. Open the web interface and enter the details of your media server and your API keys in the configuration. To reach a media server in another stack, see the [DNS section of the standard setup](../../documentation/standard-setup.md#dns). -```sh -mkdir -p posterizarr-data/config posterizarr-data/assets posterizarr-data/assetsbackup posterizarr-data/manualassets -sudo chown -R 1000:1000 posterizarr-data -``` +## Links + +- [Posterizarr documentation and source code](https://github.com/fscorrupt/Posterizarr) diff --git a/services/prowlarr/README.md b/services/prowlarr/README.md index ba0c486c..5a28fc9c 100644 --- a/services/prowlarr/README.md +++ b/services/prowlarr/README.md @@ -1,11 +1,34 @@ -# Prowlarr with Tailscale Sidecar Configuration +# Prowlarr -This Docker Compose configuration sets up [Prowlarr](https://github.com/Prowlarr/Prowlarr) with Tailscale as a sidecar container to securely manage and access your indexer management system over a private Tailscale network. By using Tailscale in a sidecar configuration, you can enhance the security and privacy of your Prowlarr instance, ensuring that it is only accessible within your Tailscale network. +[Prowlarr](https://github.com/Prowlarr/Prowlarr) manages your Usenet indexers and torrent trackers in one place and passes them on to applications such as Radarr and Sonarr. -## Prowlarr +This stack runs Prowlarr with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Prowlarr](https://github.com/Prowlarr/Prowlarr) is an open-source, self-hosted application that acts as an indexer manager for popular media automation tools such as Radarr, Sonarr, Lidarr, and Readarr. It supports a wide variety of torrent and Usenet indexers, consolidating their configuration into one place. This configuration leverages Tailscale to securely connect to your Prowlarr instance, ensuring that your indexer management interface is protected from unauthorized access and that your instance is only accessible via your private Tailscale network. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | ----------------------------------- | +| Web interface | `https://prowlarr..ts.net` | +| Service port | `9696` | +| Image | `lscr.io/linuxserver/prowlarr` | +| Data | `./prowlarr-data` | -In this setup, the `tailscale-prowlarr` service runs Tailscale, which manages secure networking for the Prowlarr service. The `prowlarr` service uses the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This setup ensures that Prowlarr’s web interface and API are only accessible through the Tailscale network (or locally, if preferred), providing an extra layer of security and privacy for your self-hosted indexer manager. +## Before you start + +Nothing beyond the [Quick Start](../../README.md#quick-start). + +## Deviations from the standard setup + +None. + +## First run + +Open the web interface. Prowlarr asks you to choose an authentication method and to create a username and password before you can continue. + +Then add your indexers, and add Radarr and Sonarr under **Settings** > **Apps**. To reach an application in another stack, see the [DNS section of the standard setup](../../documentation/standard-setup.md#dns). + +## Links + +- [Prowlarr documentation](https://wiki.servarr.com/prowlarr) +- [Prowlarr source code](https://github.com/Prowlarr/Prowlarr) +- [LinuxServer.io image documentation](https://docs.linuxserver.io/images/docker-prowlarr/) diff --git a/services/qbittorrent/README.md b/services/qbittorrent/README.md index 529520ad..6c4209cf 100644 --- a/services/qbittorrent/README.md +++ b/services/qbittorrent/README.md @@ -1,11 +1,40 @@ -# qBittorrent with Tailscale Sidecar Configuration +# qBittorrent -This Docker Compose configuration sets up [qBittorrent](https://www.qbittorrent.org/) with Tailscale as a sidecar container to securely manage and access your torrent client over a private Tailscale network. By using Tailscale in a sidecar configuration, you can enhance the security and privacy of your qBittorrent instance, ensuring that it is only accessible within your Tailscale network. +[qBittorrent](https://www.qbittorrent.org/) is a BitTorrent client with a web interface. -## qBittorrent +This stack runs qBittorrent with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[qBittorrent](https://www.qbittorrent.org/) is an open-source, cross-platform torrent client that offers a clean interface, powerful search capabilities, and support for most features found in modern BitTorrent clients. This configuration leverages Tailscale to securely connect to your qBittorrent instance, ensuring that your torrent management interface is protected from unauthorized access and that your instance is accessible only via your private Tailscale network. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | ------------------------------------------- | +| Web interface | `https://qbittorrent..ts.net` | +| Service port | `8080` | +| Image | `lscr.io/linuxserver/qbittorrent` | +| Data | `./qbittorrent-data/config` (configuration) | +| | `./qbittorrent-data/downloads` (downloads) | -In this setup, the tailscale-qbittorrent service runs Tailscale, which manages secure networking for the qBittorrent service. The qbittorrent service uses the Tailscale network stack via Docker's network_mode: service:tailscale configuration. This setup ensures that qBittorrent’s web interface and API are only accessible through the Tailscale network (or locally, if preferred), providing an extra layer of security and privacy for your self-hosted torrent client. +## Before you start + +To store downloads elsewhere, point the `/downloads` volume in `compose.yaml` at your own folder. Applications such as Radarr and Sonarr need access to the same folder. + +## Deviations from the standard setup + +- **Torrent port.** The stack publishes no ports, so the torrent port `6881` is only reachable through your Tailnet and not from the internet. + +## First run + +1. The username is `admin`. qBittorrent prints a temporary password to the log at each start: + + ```bash + docker logs app-qbittorrent 2>&1 | grep "temporary password" + ``` + +2. Open the web interface and log in. +3. Set your own password in the settings of the web interface. Otherwise qBittorrent generates a new temporary password at every start. + +## Links + +- [qBittorrent wiki](https://github.com/qbittorrent/qBittorrent/wiki) +- [qBittorrent source code](https://github.com/qbittorrent/qBittorrent) +- [LinuxServer.io image documentation](https://docs.linuxserver.io/images/docker-qbittorrent/) diff --git a/services/radarr/README.md b/services/radarr/README.md index fad9e8e6..2a1a647b 100644 --- a/services/radarr/README.md +++ b/services/radarr/README.md @@ -1,15 +1,35 @@ -# Radarr with Tailscale Sidecar Configuration +# Radarr -This Docker Compose configuration sets up [Radarr](https://github.com/Radarr/Radarr) with Tailscale as a sidecar container to securely manage and access your media management system over a private Tailscale network. By using Tailscale in a sidecar configuration, you can enhance the security and privacy of your Radarr instance, ensuring that it is only accessible within your Tailscale network. +[Radarr](https://github.com/Radarr/Radarr) manages your movie collection. It searches Usenet and BitTorrent sources for the movies you want, sends them to your download client, and sorts the files into your library. -## Radarr +This stack runs Radarr with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Radarr](https://github.com/Radarr/Radarr) is an open-source, self-hosted application for managing movies in your media collection. It allows you to automatically download movies from Usenet and BitTorrent sources and organize them in your media library. This configuration leverages Tailscale to securely connect to your Radarr instance, ensuring that your media management interface is protected from unauthorized access and that your instance is accessible only via your private Tailscale network. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | ------------------------------------------------------------- | +| Web interface | `https://radarr..ts.net` | +| Service port | `7878` | +| Image | `lscr.io/linuxserver/radarr` | +| Data | `./radarr-data/config` (configuration and database) | +| | `./radarr-data/media/movies` (movie library, optional) | +| | `./radarr-data/downloads` (download client output, optional) | -In this setup, the `tailscale-radarr` service runs Tailscale, which manages secure networking for the Radarr service. The `radarr` service uses the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This setup ensures that Radarr’s web interface and API are only accessible through the Tailscale network (or locally, if preferred), providing an extra layer of security and privacy for your self-hosted media manager. +## Before you start -### Trouble with presets or optimal download quality, try +Point the `/movies` and `/downloads` volumes in `compose.yaml` at your movie library and at the output folder of your download client. Both are optional and default to empty folders in `./radarr-data`. Docker creates missing folders as user `root`. The container runs as user and group `1000`, which need write access to both folders. -- [Configarr with presets](https://github.com/ChillBill77/configarr-presets) +## Deviations from the standard setup + +None. + +## First run + +Open the web interface. Radarr asks you to choose an authentication method and to create a username and password before you can continue. + +## Links + +- [Radarr documentation](https://wiki.servarr.com/radarr) +- [Radarr source code](https://github.com/Radarr/Radarr) +- [LinuxServer.io image documentation](https://docs.linuxserver.io/images/docker-radarr/) +- [Configarr presets](https://github.com/ChillBill77/configarr-presets), for help with quality profiles and download quality diff --git a/services/radicale/README.md b/services/radicale/README.md index 981e3c2f..dd00b6d9 100644 --- a/services/radicale/README.md +++ b/services/radicale/README.md @@ -1,61 +1,43 @@ -# Radicale with Tailscale Sidecar Configuration +# Radicale -This Docker Compose configuration sets up [Radicale](https://radicale.org/) with Tailscale as a sidecar container to keep the app reachable over your Tailnet. +[Radicale](https://radicale.org/) is a small CalDAV and CardDAV server. It synchronises your calendars, to-do lists, and contacts between your devices. -## Radicale +This stack runs Radicale with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Radicale](https://radicale.org/) is a small but powerful CalDAV (calendars, to-do lists) and CardDAV (contacts) server. It is lightweight, easy to configure, and requires minimal resources, making it a great self-hosted alternative to cloud-based calendar and contact sync services. +## At a glance -## Key Features +| Item | Value | +| ------------- | ------------------------------------------------------ | +| Web interface | `https://radicale..ts.net` | +| Service port | `5232` | +| Image | `tomsquest/docker-radicale` | +| Data | `./radicale-data/app/data` (calendars and contacts) | +| | `./radicale-data/config/radicale.conf` (configuration) | +| | `./radicale-data/users` (users and password hashes) | -- CalDAV and CardDAV support for syncing calendars, to-do lists, and contacts -- Works with any compliant client (Thunderbird, GNOME Calendar, DAVx5, Apple Calendar, etc.) -- Lightweight with minimal resource usage -- Simple file-based storage -- Web interface for managing collections -- Built-in access control and authentication +## Before you start -## Configuration Overview +Radicale needs its configuration file and its user file before the first start. Run the commands from this directory. -In this setup, the `tailscale-radicale` service runs Tailscale, which manages secure networking for Radicale. The `radicale` service utilizes the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This keeps the app Tailnet-only unless you intentionally expose ports. - -The container runs with hardened security settings: read-only filesystem, no new privileges, dropped capabilities, and resource limits (256M memory, 50 pids). - -## Prerequisites - -- This image uses [tomsquest/docker-radicale](https://github.com/tomsquest/docker-radicale). Refer to their documentation for advanced configuration options. -- To configure users and authentication, mount a custom config file or refer to the [Radicale documentation](https://radicale.org/v3.html#configuration). - -## Creating Users - -Radicale uses `htpasswd` for authentication. To set up users: - -1. **Create the required directories:** +1. Create the configuration folder: ```bash - set -a && source .env && set +a - mkdir -p ./${SERVICE}-data/config + mkdir -p ./radicale-data/config ``` -2. **Create an `htpasswd` file** with your first user (requires `apache2-utils` on Debian/Ubuntu or `httpd-tools` on Fedora): +2. Create the user file with your first user. The `htpasswd` tool is in the package `apache2-utils` on Debian and Ubuntu, and in `httpd-tools` on Fedora. ```bash - htpasswd -B -c ./${SERVICE}-data/users + htpasswd -B -c ./radicale-data/users ``` - To add more users without overwriting the file, omit `-c`: + To add more users later, leave out `-c`, which would overwrite the file: ```bash - htpasswd -B ./${SERVICE}-data/users + htpasswd -B ./radicale-data/users ``` -3. **Fill out config file**: - - ```bash - nano ./${SERVICE}-data/config/radicale.conf - ``` - - With: +3. Create `./radicale-data/config/radicale.conf` with this content: ```ini [auth] @@ -67,14 +49,16 @@ Radicale uses `htpasswd` for authentication. To set up users: filesystem_folder = /data/collections ``` -4. **Restart the stack:** +## Deviations from the standard setup - ```bash - docker compose down && docker compose up -d - ``` +- **Configuration and user file.** The stack mounts `radicale.conf` and the user file as single files and starts Radicale with that configuration file. +- **File ownership.** `TAKE_FILE_OWNERSHIP=true` makes the image set the owner of the data folder at each start. + +## First run -## Files to check +Open the web interface and log in with a user from the user file. Create your calendars and address books there, then add the account to your devices with `https://radicale..ts.net` as the server address. -Please check the following contents for validity as some variables need to be defined upfront. +## Links -- `.env` — Main variable: `TS_AUTHKEY` +- [Radicale documentation](https://radicale.org/v3.html) +- [tomsquest/docker-radicale image](https://github.com/tomsquest/docker-radicale) diff --git a/services/recyclarr/README.md b/services/recyclarr/README.md index 8494cb9d..344fa5d3 100644 --- a/services/recyclarr/README.md +++ b/services/recyclarr/README.md @@ -1,48 +1,43 @@ -# Recyclarr with Tailscale Sidecar Configuration +# Recyclarr -This Docker Compose configuration sets up **Recyclarr** with a Tailscale sidecar container, allowing secure and private synchronization of quality profiles, custom formats, and media settings across your *Radarr* and *Sonarr* instances. With this setup, Recyclarr is **only reachable from within your Tailscale network**, keeping your media automation infrastructure fully private and protected. +[Recyclarr](https://recyclarr.dev/) synchronises the quality profiles and custom formats of the TRaSH Guides to Radarr and Sonarr. You describe the result in a YAML file, and Recyclarr keeps your applications in line with it. -## Recyclarr +This stack runs Recyclarr with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[**Recyclarr**](https://github.com/recyclarr/recyclarr) is an automation tool designed to **synchronize TRaSH-Guides–based quality profiles and custom formats** to Radarr and Sonarr. Instead of manually configuring and maintaining complex quality rules, Recyclarr allows you to define everything declaratively in YAML and keep your media stack consistent and reproducible. +## At a glance -## Key Features +| Item | Value | +| ------------- | -------------------------------------------------------------- | +| Web interface | None | +| Image | `ghcr.io/recyclarr/recyclarr:8` | +| Data | `./recyclarr-data/config` (your `recyclarr.yml` and the state) | -* ♻️ **TRaSH-Guides Integration** – Automatically syncs recommended quality profiles and custom formats. -* 📐 **Declarative Configuration** – Manage Radarr and Sonarr settings using simple YAML files. -* 🔄 **Consistent Media Rules** – Keep multiple Radarr/Sonarr instances aligned. -* 🧩 **Custom Format Management** – Automatically create, update, and score custom formats. -* 🧪 **Dry-Run Support** – Preview changes before applying them. -* 🐳 **Docker-Friendly** – Lightweight container designed for scheduled or on-demand runs. -* 🛠 **Automation-First** – Ideal for cron jobs, CI pipelines, or homelab orchestration. +## Before you start -## Why Self-Host? +Create the configuration folder yourself and make user `1000` its owner. Docker creates missing folders as user `root`. The stack runs Recyclarr as user and group `1000`, and it then exits with `Access to the path '/config/state' is denied`. -Recyclarr requires **API access to Radarr and Sonarr**, which often exposes sensitive configuration details about your media infrastructure. By self-hosting Recyclarr and restricting access via Tailscale, you ensure: - -* Your Radarr/Sonarr APIs are never exposed publicly -* All synchronization traffic stays inside your private network -* Remote management remains secure, even when traveling or managing multiple sites - -This is especially valuable in homelabs, seedbox setups, or multi-location media deployments. - -## Configuration Overview +```bash +mkdir -p recyclarr-data/config +sudo chown -R 1000:1000 recyclarr-data +``` -In this deployment, a **Tailscale sidecar container** (for example, `tailscale-recyclarr`) runs the Tailscale client and joins your private Tailscale network. The Recyclarr service uses: +## Deviations from the standard setup -```plain -network_mode: service:tailscale -``` +- **No web interface.** The stack has no Tailscale Serve configuration and no `./config` folder. Recyclarr only makes outgoing connections to your applications. +- **Fixed user.** The `application` container runs as user and group `1000` through the `user` setting. +- **Starter configuration.** `RECYCLARR_CREATE_CONFIG=true` makes Recyclarr create a sample `recyclarr.yml` at the first start. -This setup ensures that **all Recyclarr traffic flows exclusively through the Tailscale interface**, allowing it to securely reach Radarr and Sonarr instances that are also on your Tailscale network. No ports need to be exposed, and the container remains completely inaccessible from the public Internet. +## First run -With this configuration, Recyclarr can safely automate and enforce your media quality standards across your entire media stack — privately, securely, and reproducibly. +1. Start the stack once. Recyclarr creates `recyclarr.yml` in `./recyclarr-data/config`. +2. Add the address and API key of Radarr and Sonarr to that file, and choose the profiles to synchronise. To reach an application in another stack, see the [DNS section of the standard setup](../../documentation/standard-setup.md#dns). +3. Restart the stack. The container then synchronises once a day. To run a sync right away: -## Volume Permissions + ```bash + docker compose exec application recyclarr sync + ``` -The Compose file runs Recyclarr as UID/GID `1000`. Docker creates missing bind-mount directories as `root:root`, and Recyclarr then exits with `Access to the path '/config/state' is denied`. Create the config directory before the first start: +## Links -```sh -mkdir -p recyclarr-data/config -sudo chown -R 1000:1000 recyclarr-data -``` +- [Recyclarr documentation](https://recyclarr.dev/wiki/) +- [Recyclarr source code](https://github.com/recyclarr/recyclarr) diff --git a/services/resilio-sync/README.md b/services/resilio-sync/README.md index 1806c34a..d9142866 100644 --- a/services/resilio-sync/README.md +++ b/services/resilio-sync/README.md @@ -1,11 +1,33 @@ -# Resilio Sync with Tailscale Sidecar Configuration +# Resilio Sync -This Docker Compose configuration sets up [Resilio Sync](https://github.com/linuxserver/docker-resilio-sync) with Tailscale as a sidecar container to securely synchronize and share your files over a private Tailscale network. By using Tailscale in a sidecar configuration, you can enhance the security and privacy of your file synchronization, ensuring that Resilio Sync is only accessible within your Tailscale network. +[Resilio Sync](https://www.resilio.com/sync/) synchronises folders directly between your devices, without a central server. -## Resilio Sync +This stack runs Resilio Sync with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Resilio Sync](https://github.com/linuxserver/docker-resilio-sync) is a powerful, peer-to-peer file synchronization tool that allows you to sync files between devices or share them with others, without relying on cloud services. With its robust and flexible syncing capabilities, Resilio Sync is ideal for personal and professional use cases where secure, decentralized file sharing is required. This configuration leverages Tailscale to securely connect to your Resilio Sync instance, protecting your file transfers from unauthorized access. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | --------------------------------------------------------------------------- | +| Web interface | `https://resilio-sync..ts.net` | +| Service port | `8888` | +| Image | `linuxserver/resilio-sync` | +| Data | `./resilio-sync-data/config` (configuration) | +| | `./resilio-sync-data/data` (synchronised folders, `/sync` in the container) | +| | `./resilio-sync-data/downloads` (downloads) | -In this setup, the `tailscale-resilio-sync` service runs Tailscale, which manages secure networking for the Resilio Sync service. The `resilio-sync` service uses the Tailscale network stack via Docker’s `network_mode: service:tailscale` configuration. This setup ensures that Resilio Sync is only accessible through the Tailscale network (or locally, if preferred), providing an extra layer of security and privacy for your file synchronization and sharing tasks. +## Before you start + +To synchronise existing folders, point the `/sync` volume in `compose.yaml` at your own folder. The container runs as user and group `1000`, which need write access to it. + +## Deviations from the standard setup + +- **Sync port.** The stack publishes no ports, so the sync port `55555` is only reachable through your Tailnet and not from your local network or the internet. + +## First run + +Open the web interface and create the username and password for it. Then add your folders below `/sync`. + +## Links + +- [Resilio Sync website](https://www.resilio.com/sync/) +- [LinuxServer.io image documentation](https://docs.linuxserver.io/images/docker-resilio-sync/) diff --git a/services/rustdesk-server/README.md b/services/rustdesk-server/README.md index a132c3c1..c4fd9728 100644 --- a/services/rustdesk-server/README.md +++ b/services/rustdesk-server/README.md @@ -1,27 +1,46 @@ -# Rustdesk Server with Tailscale Sidecar Configuration +# RustDesk Server -This Docker Compose configuration sets up [Rustdesk Server](https://rustdesk.com/docs/en/) with Tailscale as a sidecar container to keep the app reachable over your Tailnet. +[RustDesk](https://rustdesk.com/) is a remote desktop application. This stack runs its own ID and relay server, so that your RustDesk clients find and reach each other without the public servers. -## Rustdesk Server +This stack runs RustDesk Server with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Rustdesk Server](https://rustdesk.com/docs/en/) information about the service. Explain what the app does in 2-3 sentences and why someone would pair it with Tailscale. +## At a glance -## Configuration Overview +| Item | Value | +| --------------------- | -------------------------------------------------------------------------------------------------- | +| Web interface | None | +| ID server (`hbbs`) | Ports `21115`, `21116` (TCP and UDP), and `21118` on the Tailscale IP address of `rustdesk-server` | +| Relay server (`hbbr`) | Ports `21117` and `21119` on the Tailscale IP address of `rustdesk-server` | +| Image | `rustdesk/rustdesk-server` | +| Data | `./rustdesk-server-data/hbbs` (key pair and database of the ID server) | +| | `./rustdesk-server-data/hbbr` (data of the relay server) | -In this setup, the `tailscale-rustdesk-server` service runs Tailscale, which manages secure networking for Rustdesk Server. The `Rustdesk Server` service utilizes the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This keeps the app Tailnet-only unless you intentionally expose ports. +## Before you start -## Client setup +Nothing beyond the [Quick Start](../../README.md#quick-start). -- Service Configuration: The Rustdesk client public Key credentials are generated at first run and stored in the **id_ed25519.pub** file. This is found in the compose directory **./rustdesk-server-data/hbbs/** Clients can be setup using the --config switch. e.g. **rustdesk.exe --config "host=rustdesk-server.your-tailnet.ts.net,key=Public_Key_Credentials"** or in the client: Setting -> Network -> ID/Relay Server. Add **ID server** (e.g. rustdesk-server.your-tailnet.ts.net) and **Key**. There is no need to configure the Relay server or API server. +## Deviations from the standard setup -Links: +- **Two application containers.** The `application` container runs the ID server `hbbs`, and the `hbbr` container runs the relay server. Both use the network of the `tailscale` container. +- **No web interface.** The clients connect directly to the ports of the device on your Tailnet. The Tailscale Serve configuration from the template has no use here. +- **Relay setting.** `ALWAYS_USE_RELAY` in `.env` is `N`. Set it to `Y` to send all connections through the relay server. -- [Client setup](https://github.com/rustdesk/rustdesk/discussions/7118) -- [Rustdesk](https://rustdesk.com/) -- [Client Configuration](https://rustdesk.com/docs/en/self-host/client-configuration/) +## First run -## Files to check +1. Start the stack. The ID server creates its key pair at the first start. Read the public key: -Please check the following contents for validity as some variables need to be defined upfront. + ```bash + cat ./rustdesk-server-data/hbbs/id_ed25519.pub + ``` -- `.env` // Main variable `TS_AUTHKEY` +2. In each RustDesk client, open **Settings** > **Network** > **ID/Relay Server**. Enter `rustdesk-server..ts.net` as the **ID server** and the public key as the **Key**. You do not need to fill in the relay server or the API server. + + You can also pass both values on the command line, for example `rustdesk.exe --config "host=rustdesk-server..ts.net,key="`. + +All clients must be on your Tailnet. + +## Links + +- [RustDesk self-hosting documentation](https://rustdesk.com/docs/en/self-host/) +- [RustDesk client configuration](https://rustdesk.com/docs/en/self-host/client-configuration/) +- [RustDesk server source code](https://github.com/rustdesk/rustdesk-server) diff --git a/services/seafile/README.md b/services/seafile/README.md index 684d5c96..79d2e356 100644 --- a/services/seafile/README.md +++ b/services/seafile/README.md @@ -1,44 +1,63 @@ -# Seafile with Tailscale Sidecar Configuration +# Seafile -This Docker Compose configuration sets up [Seafile Community Edition](https://www.seafile.com/en/product/seafile_on_premise/) with Tailscale as a sidecar container to keep the app reachable over your Tailnet. +[Seafile Community Edition](https://www.seafile.com/en/product/seafile_on_premise/) is a file synchronisation and sharing platform. You store your files in libraries, synchronise them with the desktop and mobile clients, and share them with others. -## Seafile +This stack runs Seafile with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Seafile Community Edition](https://www.seafile.com/en/product/seafile_on_premise/) is an open‑source, self‑hosted file syncing and collaboration platform that lets individuals and small teams store, share, and version their files on their own servers. It provides fast, reliable file synchronization and team collaboration features. Think self-hosted OneDrive or Dropbox. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | -------------------------------------------------------- | +| Web interface | `https://seafile..ts.net` | +| Service port | `80` | +| Images | `seafileltd/seafile-mc:13.0-latest` | +| | `mariadb:10.11` | +| | `memcached:1.6.29` | +| Data | `./seafile-data` (Seafile, set by `SEAFILE_VOLUME`) | +| | `./db` (MariaDB database, set by `SEAFILE_MYSQL_VOLUME`) | -In this setup, the `tailscale-seafile` service runs Tailscale, which manages secure networking for Seafile. The Seafile service utilizes the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This keeps the app Tailnet-only unless you intentionally expose ports. +## Before you start -## Notes +Set these values in `.env`: -- This configuration is intended for small (single digit) groups of users. It omits the SeaDoc, Collabora and Notification servers, and uses Memcached instead of Redis. You would probably want all of those things in a large deployment. -- Keep `SEAFILE_MEMCACHED_IMAGE` on a Debian-based tag. The Memcached health check needs perl, which Alpine tags lack, and Seafile waits for Memcached to be healthy before it starts. -- Additional Docker Compose settings for Seafile can be found here: +- **`SEAFILE_SERVER_HOSTNAME`.** The name of the device on your Tailnet, `seafile..ts.net`. +- **`INIT_SEAFILE_MYSQL_ROOT_PASSWORD` and `SEAFILE_MYSQL_DB_PASSWORD`.** The passwords of the database. Use random values of letters and digits. +- **`INIT_SEAFILE_ADMIN_EMAIL` and `INIT_SEAFILE_ADMIN_PASSWORD`.** The administrator account that Seafile creates at the first start. The address does not need to exist, unless you configure email notifications later. +- **`JWT_PRIVATE_KEY`.** A random value. Generate one with `openssl rand -base64 40`. +- **`SEAFILE_VOLUME` and `SEAFILE_MYSQL_VOLUME`.** The data folders. Change them to store the data elsewhere. -## Files to check +MariaDB and Seafile apply the database passwords only at the first start. -Please check the following contents for validity as some variables need to be defined upfront. +## Deviations from the standard setup -- `TS_AUTHKEY`: Paste in an Auth Key for your Tailnet. -- Volumes: Update the locations for the `SEAFILE_VOLUME` and `SEAFILE_MYSQL_VOLUME` in .ENV. -- Passwords: There are three passwords (for MySQL/MariaDB and initial Seafile administrator) which need to be set in .ENV. -- Admin Email: Update `INIT_SEAFILE_ADMIN_EMAIL`. This doesn't have to be a valid email address, although you can configure SMTP notifications in Seafile, which will require a valid email address. -- `JWT_PRIVATE_KEY`: Generate this by running `pwgen -s 40 1` or `openssl rand -base64 40` -- `SEAFILE_SERVER_HOSTNAME`: Update the FQDN to match your Tailnet MagicDNS suffix. +- **Service names.** The application service is called `seafile`, not `application`, and its container has no fixed name. +- **Extra containers.** The stack runs `db` (MariaDB) and `memcached`. They use the default Compose network, and Seafile reaches them by their service name through Docker's DNS. Keep `TS_ACCEPT_DNS` disabled, because MagicDNS cannot resolve these names. +- **Images are set in `.env`.** The stack does not use `IMAGE_URL`. `SEAFILE_IMAGE`, `SEAFILE_DB_IMAGE`, and `SEAFILE_MEMCACHED_IMAGE` select the images. Keep the Memcached image on a Debian-based tag, because its health check needs `perl`, which Alpine tags lack. +- **Small deployment.** The stack is meant for a handful of users. It leaves out the SeaDoc, Collabora, and notification servers, and it uses Memcached instead of Redis. +- **Data folders.** The data is in `./seafile-data` and `./db`. + +## First run + +Open the web interface and log in with the administrator account from `.env`. ## Troubleshooting ### Seafile cannot connect to the database -Seafile waits for the database before it starts and logs nothing while it waits. The `app-seafile` container stays up, turns `unhealthy`, and the web interface answers `502 Bad Gateway`. Two causes are common. +Seafile waits for the database before it starts and logs nothing while it waits. The Seafile container stays up, turns `unhealthy`, and the web interface answers `502 Bad Gateway`. Two causes are common. -**`TS_ACCEPT_DNS=true` is enabled.** Seafile shares the network of the Tailscale container and reaches the database and Memcached through the Compose service names `db` and `memcached`. With `TS_ACCEPT_DNS=true`, Tailscale replaces Docker DNS and those names no longer resolve. Check whether the names resolve: +**`TS_ACCEPT_DNS=true` is enabled.** With this setting, Tailscale replaces Docker's DNS, and the names `db` and `memcached` no longer resolve. Check whether the names resolve: ```bash -docker exec app-seafile getent hosts db memcached +docker compose exec seafile getent hosts db memcached ``` If the command prints nothing, comment out `TS_ACCEPT_DNS` in `compose.yaml` and run `docker compose up -d`. Seafile does not need MagicDNS, and Tailscale Serve works without this setting. -**The database passwords changed after the first start.** MariaDB applies `INIT_SEAFILE_MYSQL_ROOT_PASSWORD` only when it creates an empty data directory, and Seafile creates its database user with `SEAFILE_MYSQL_DB_PASSWORD` on the first start. Later changes in `.env` do not reach the existing database, so Seafile can no longer log in and `docker logs app-seafile-db` shows `Access denied for user`. Restore the original passwords. On a new installation without data, you can instead stop the stack, delete the `SEAFILE_MYSQL_VOLUME` and `SEAFILE_VOLUME` directories, and start again. +**The database passwords changed after the first start.** Later changes in `.env` do not reach the existing database, so Seafile can no longer log in, and `docker logs app-seafile-db` shows `Access denied for user`. Restore the original passwords. On a new installation without data, you can instead stop the stack, delete the folders from `SEAFILE_MYSQL_VOLUME` and `SEAFILE_VOLUME`, and start again. + +## Links + +- [Seafile Docker setup](https://manual.seafile.com/latest/setup/setup_ce_by_docker/) +- [Seafile administration manual](https://manual.seafile.com/latest/) +- [Seafile source code](https://github.com/haiwen/seafile) diff --git a/services/searxng/README.md b/services/searxng/README.md index 6b42d634..7ab21f0b 100644 --- a/services/searxng/README.md +++ b/services/searxng/README.md @@ -1,20 +1,40 @@ -# searXNG with Tailscale Sidecar Configuration +# SearXNG -This Docker Compose configuration sets up [searXNG](https://github.com/searxng/searxng) with Tailscale as a sidecar container, enabling secure access to your private metasearch engine over a private Tailscale network. By integrating Tailscale in a sidecar configuration, you can ensure that your searXNG instance is accessible only within your Tailscale network, providing an additional layer of security and privacy for your searches. +[SearXNG](https://github.com/searxng/searxng) is a metasearch engine. It combines the results of many search engines and does not track or profile its users. -## searXNG +This stack runs SearXNG with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[searXNG](https://github.com/searxng/searxng) is a free, open-source metasearch engine that aggregates results from multiple search engines while protecting your privacy. With no user tracking and the ability to self-host, searXNG empowers you to take control of your search experience. By leveraging Tailscale, you can securely access your self-hosted searXNG instance from any of your devices, ensuring that your searches remain private and inaccessible to unauthorized users. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | ------------------------------------------- | +| Web interface | `https://searxng..ts.net` | +| Service port | `8080` | +| Images | `docker.io/searxng/searxng` | +| | `docker.io/valkey/valkey:8-alpine` | +| Data | `./searxng` (configuration, `settings.yml`) | +| | Docker volume `valkey-data2` (Valkey data) | -In this setup, the `tailscale-searxng` service runs Tailscale, which manages secure networking for the searXNG service. The `searxng` service utilizes the Tailscale network stack via Docker’s `network_mode: service:tailscale` configuration. This setup ensures that searXNG is only accessible through your Tailscale network (or locally, if preferred). With this configuration, you can enjoy a private, secure, and customizable search engine experience, free from user tracking or external access. +## Before you start -We use `/searxng/settings.yml` copied from as the default settings file. This dir is mounted as a volume, on docker and required for the first run. -The default `settings.yml` does not use valkey ([valkey](https://github.com/searxng/searxng/blob/master/searx/settings.yml#L121) URL is set to `false`). We enable this by setting the `SEARXNG_VALKEY_URL` in `.env` file and using that in the `compose.yaml` file. -Set `SEARXNG_SECRET` in `.env` to a random value, for example with `openssl rand -hex 32`. The Compose file passes it to the mounted settings file as the instance secret, and Compose stops with an error if it is empty. -Set `TAILNET_NAME` in `.env` to your Tailnet name, the part between the service name and `.ts.net`. The Compose file builds the base URL `https://..ts.net/` from it. SearXNG uses it to build its inbound links, and an empty value would produce an invalid address, so Compose stops with an error if `TAILNET_NAME` is empty. +Set these values in `.env`. Compose stops with an error if one of them is empty. -## References +- **`TAILNET_NAME`.** Your Tailnet name, the part between the service name and `.ts.net`. `compose.yaml` builds the base address `https://..ts.net/` from it, which SearXNG uses for its links. +- **`SEARXNG_SECRET`.** A random value. Generate one with `openssl rand -hex 32`. -[![Replace Google with SearXNG - a privacy respecting, self-hosted search engine](https://img.youtube.com/vi/cg9d87PuanE/0.jpg)](https://www.youtube.com/watch?v=cg9d87PuanE) +## Deviations from the standard setup + +- **Settings file.** This directory contains `searxng/settings.yml`, a copy of the [default settings of SearXNG](https://github.com/searxng/searxng/blob/master/searx/settings.yml). The stack mounts the folder at `/etc/searxng`. Edit that file to change the engines and other settings. +- **Extra container.** The stack runs a `valkey` container on the default Compose network. `SEARXNG_VALKEY_URL` in `.env` points SearXNG at it, because the default settings do not use Valkey. Keep `TS_ACCEPT_DNS` disabled, because MagicDNS cannot resolve the name `valkey`. +- **Reduced privileges.** Both containers drop all capabilities and add back only the few that they need. +- **Log size.** Both containers limit their log to one file of 1 MB. + +## First run + +Nothing to set up. Open the web interface and search. SearXNG has no login. + +## Links + +- [SearXNG documentation](https://docs.searxng.org/) +- [SearXNG source code](https://github.com/searxng/searxng) +- [Video: replace Google with SearXNG](https://www.youtube.com/watch?v=cg9d87PuanE) diff --git a/services/seerr/README.md b/services/seerr/README.md index 19625ab4..727e6af7 100644 --- a/services/seerr/README.md +++ b/services/seerr/README.md @@ -1,22 +1,36 @@ -# Seerr with Tailscale Sidecar Configuration +# Seerr -This Docker Compose configuration sets up [Seerr](https://github.com/seerr-team/seerr) with Tailscale as a sidecar container to securely manage and access your request management system over a private Tailscale network. By integrating Tailscale in a sidecar configuration, you enhance the privacy and security of your Seerr instance, ensuring it is only accessible within your Tailscale network. +[Seerr](https://github.com/seerr-team/seerr) is a request manager for your media library. Users search for movies and series and request them, and Seerr passes approved requests to Radarr and Sonarr. It works with Plex, Jellyfin, and Emby. -## Seerr +This stack runs Seerr with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Seerr](https://github.com/seerr-team/seerr) is an open-source request management and media discovery tool built to work with Plex, Jellyfin and Emby. It allows users to search and request media, track request status, and manage users in a visually appealing and user-friendly interface. By pairing Seer with Tailscale, your instance becomes securely accessible through a zero-config mesh VPN, preventing unauthorized access over the public internet. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | -------------------------------- | +| Web interface | `https://seerr..ts.net` | +| Service port | `5055` | +| Image | `ghcr.io/seerr-team/seerr` | +| Data | `./seerr-data/config` | -In this setup, the `tailscale-seerr` service runs the Tailscale daemon to provide secure, private networking. The `seerr` service is configured to use Tailscale’s network stack via Docker’s `network_mode: service:tailscale` syntax. This binds Seer’s network interface to the Tailscale container, making the web UI and API available only through your Tailscale network (or locally, if needed). +## Before you start -This architecture is ideal for self-hosters who want to access Seerr from anywhere without exposing it to the internet, maintaining both ease of access and strict privacy controls. +Create the configuration folder yourself and make user `1000` its owner. Docker creates missing folders as user `root`. The Seerr image runs as user and group `1000`, and it then exits with `EACCES` when it creates `/app/config/logs`. -## Volume Permissions - -The Seerr image runs as the non-root `node` user (UID/GID `1000`). Docker creates missing bind-mount directories as `root:root`, and Seerr then exits with `EACCES` when it creates `/app/config/logs`. Create the config directory before the first start: - -```sh +```bash mkdir -p seerr-data/config sudo chown -R 1000:1000 seerr-data ``` + +## Deviations from the standard setup + +- **Log level.** `compose.yaml` sets `LOG_LEVEL=debug`. + +## First run + +Open the web interface and follow the setup. You choose your media server, sign in with it, and add Radarr and Sonarr. To reach an application in another stack, see the [DNS section of the standard setup](../../documentation/standard-setup.md#dns). + +## Links + +- [Seerr documentation](https://docs.seerr.dev/) +- [Seerr source code](https://github.com/seerr-team/seerr) diff --git a/services/slink/README.md b/services/slink/README.md index 571111f4..fd6e0649 100644 --- a/services/slink/README.md +++ b/services/slink/README.md @@ -1,11 +1,43 @@ -# Slink with Tailscale Sidecar Configuration +# Slink -This Docker Compose configuration sets up [Slink](https://github.com/andrii-kryvoviaz/slink) with Tailscale as a sidecar container to securely manage and access your local file-sharing system over a private Tailscale network. By integrating Tailscale in a sidecar configuration, you can ensure that your Slink instance is both secure and private, accessible only within your Tailscale network. +[Slink](https://github.com/andrii-kryvoviaz/slink) is an image sharing platform. You upload images and share them with a link. -## Slink +This stack runs Slink with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Slink](https://github.com/andrii-kryvoviaz/slink) is a fast, self-hosted alternative to ShareDrop, enabling secure, real-time file sharing over local networks. It allows you to easily share files between devices without relying on third-party servers, ensuring complete control and privacy. By combining Slink with Tailscale, this configuration provides a secure way to connect and share files exclusively within your private network. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | ------------------------------------------ | +| Web interface | `https://slink..ts.net` | +| Service port | `3000` | +| Image | `anirdev/slink` | +| Data | `./slink-data/var/data` (application data) | +| | `./slink-data/images` (uploaded images) | -In this setup, the `tailscale-slink` service runs Tailscale, which manages secure networking for the Slink service. The `slink` service uses the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This ensures that Slink's file-sharing interface is only accessible through the Tailscale network, adding an extra layer of security and privacy for your self-hosted file-sharing system. +## Before you start + +Set `ORIGIN` in `compose.yaml` to the address of the web interface, `https://slink..ts.net`. Slink needs the correct address for its cookies, so the sample value `https://your-domain.com` does not work. + +## Deviations from the standard setup + +None. + +## First run + +1. Open `https://slink..ts.net/profile/signup` and create your account. +2. The stack sets `USER_APPROVAL_REQUIRED=true`, so a new account must be activated first: + + ```bash + docker exec -it app-slink slink user:activate --email= + ``` + +3. Make your account an administrator: + + ```bash + docker exec -it app-slink slink user:grant:role --email= ROLE_ADMIN + ``` + +## Links + +- [Slink documentation](https://docs.slinkapp.io/) +- [Slink source code](https://github.com/andrii-kryvoviaz/slink) diff --git a/services/sonarr/README.md b/services/sonarr/README.md index 3c6cfa9a..acb698f7 100644 --- a/services/sonarr/README.md +++ b/services/sonarr/README.md @@ -1,15 +1,35 @@ -# Sonarr with Tailscale Sidecar Configuration +# Sonarr -This Docker Compose configuration sets up [Sonarr](https://github.com/Sonarr/Sonarr) with Tailscale as a sidecar container to securely manage and access your media management system over a private Tailscale network. By using Tailscale in a sidecar configuration, you can enhance the security and privacy of your Sonarr instance, ensuring that it is only accessible within your Tailscale network. +[Sonarr](https://github.com/Sonarr/Sonarr) manages your series collection. It searches Usenet and BitTorrent sources for new episodes, sends them to your download client, and sorts the files into your library. -## Sonarr +This stack runs Sonarr with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Sonarr](https://github.com/Sonarr/Sonarr) is an open-source, self-hosted application for managing TV shows in your media collection. It allows you to automatically download TV episodes from Usenet and BitTorrent sources and organize them in your media library. This configuration leverages Tailscale to securely connect to your Sonarr instance, ensuring that your media management interface is protected from unauthorized access and that your instance is accessible only via your private Tailscale network. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | ------------------------------------------------------------ | +| Web interface | `https://sonarr..ts.net` | +| Service port | `8989` | +| Image | `lscr.io/linuxserver/sonarr` | +| Data | `./sonarr-data/config` (configuration and database) | +| | `./sonarr-data/media/tvseries` (series library, optional) | +| | `./sonarr-data/downloads` (download client output, optional) | -In this setup, the tailscale-sonarr service runs Tailscale, which manages secure networking for the Sonarr service. The sonarr service uses the Tailscale network stack via Docker's network_mode: service:tailscale configuration. This setup ensures that Sonarr’s web interface and API are only accessible through the Tailscale network (or locally, if preferred), providing an extra layer of security and privacy for your self-hosted media manager. +## Before you start -### Trouble with presets or optimal download quality, try +Point the `/tv` and `/downloads` volumes in `compose.yaml` at your series library and at the output folder of your download client. Both are optional and default to empty folders in `./sonarr-data`. Docker creates missing folders as user `root`. The container runs as user and group `1000`, which need write access to both folders. -- [Configarr with presets](https://github.com/ChillBill77/configarr-presets) +## Deviations from the standard setup + +None. + +## First run + +Open the web interface. Sonarr asks you to choose an authentication method and to create a username and password before you can continue. + +## Links + +- [Sonarr documentation](https://wiki.servarr.com/sonarr) +- [Sonarr source code](https://github.com/Sonarr/Sonarr) +- [LinuxServer.io image documentation](https://docs.linuxserver.io/images/docker-sonarr/) +- [Configarr presets](https://github.com/ChillBill77/configarr-presets), for help with quality profiles and download quality diff --git a/services/speedtest-tracker/README.md b/services/speedtest-tracker/README.md index 476bb0f6..3ff00d93 100644 --- a/services/speedtest-tracker/README.md +++ b/services/speedtest-tracker/README.md @@ -1,28 +1,38 @@ -# Speedtest Tracker with Tailscale Sidecar Configuration +# Speedtest Tracker -This Docker Compose configuration sets up [Speedtest Tracker](https://github.com/alexjustesen/speedtest-tracker) with Tailscale as a sidecar container to securely monitor and access your internet speed tracking tool over a private Tailscale network. By integrating Tailscale, you can ensure that your Speedtest Tracker instance remains private and accessible only to authorized devices on your Tailscale network. +[Speedtest Tracker](https://docs.speedtest-tracker.dev/) tests the speed of your internet connection on a schedule. It keeps the history and shows it in graphs. -## Speedtest Tracker +This stack runs Speedtest Tracker with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Speedtest Tracker](https://github.com/alexjustesen/speedtest-tracker) is an open-source, self-hosted tool designed to regularly test and monitor your internet connection speed. It logs historical speed test data and provides detailed visualizations, making it ideal for diagnosing network issues or keeping your ISP accountable. Adding Tailscale enhances the security of your Speedtest Tracker instance by ensuring access is limited to authorized devices within your private network. +## At a glance -## Key Features +| Item | Value | +| ------------- | ------------------------------------------------------- | +| Web interface | `https://speedtest-tracker..ts.net` | +| Service port | `8888` | +| Image | `lscr.io/linuxserver/speedtest-tracker` | +| Data | `./speedtest-tracker-data` (configuration and database) | +| | `./nginx/default.conf` (web server configuration) | -- **Automated Speed Tests**: Schedule regular speed tests for consistent monitoring. -- **Data Logging**: Keep historical records of your upload, download, and ping stats. -- **Detailed Visualizations**: View trends and performance over time with an intuitive web interface. -- **Self-Hosted**: Maintain full control over your data with a locally hosted solution. +## Before you start -## Configuration Overview +Set `APP_KEY` in `.env`. Generate the value with `echo "base64:$(openssl rand -base64 32)"`. Compose stops with an error if it is empty. -In this setup, the `tailscale-speedtest` service runs Tailscale, which manages secure networking for the Speedtest Tracker service. The `speedtest-tracker` service uses the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This ensures that Speedtest Tracker’s web interface is only accessible through the Tailscale network (or locally, if preferred), providing enhanced privacy and security for your internet speed monitoring. +## Deviations from the standard setup -## Files to check +- **Web server port.** This directory contains `nginx/default.conf`, which makes the web server in the container listen on port `8888`. The stack mounts it over the configuration of the image. +- **Database.** `DB_CONNECTION=sqlite` makes Speedtest Tracker store its data in a SQLite database in the data folder. -Please check the following contents for validity as some variables need to be defined upfront. +## First run -- `.env` - - Required: `TS_AUTHKEY` - - Required: `APP_KEY`. Generate it with `echo "base64:$(openssl rand -base64 32)"`. Compose stops with an error if it is empty. +Open the web interface and log in with the default account `admin@example.com` and password `password`. Change both right after you log in. -If you previously set `APP_KEY` in `compose.yaml`, move that value to `.env`. A new key cannot decrypt data that Speedtest Tracker already encrypted. +## Upgrading + +If you set `APP_KEY` in `compose.yaml` before, move that value to `.env`. A new key cannot decrypt the data that Speedtest Tracker already encrypted. + +## Links + +- [Speedtest Tracker documentation](https://docs.speedtest-tracker.dev/) +- [Speedtest Tracker source code](https://github.com/alexjustesen/speedtest-tracker) +- [LinuxServer.io image documentation](https://docs.linuxserver.io/images/docker-speedtest-tracker/) diff --git a/services/stirlingpdf/README.md b/services/stirlingpdf/README.md index 122268a1..043b5e9e 100644 --- a/services/stirlingpdf/README.md +++ b/services/stirlingpdf/README.md @@ -1,11 +1,32 @@ -# Stirling-PDF with Tailscale Sidecar Configuration +# Stirling-PDF -This Docker Compose configuration sets up [Stirling-PDF](https://github.com/Stirling-Tools/Stirling-PDF) with Tailscale as a sidecar container to securely manage and manipulate PDF files over a private Tailscale network. By using Tailscale in a sidecar configuration, you can enhance the security and privacy of your PDF processing, ensuring that the Stirling-PDF interface is only accessible within your Tailscale network. +[Stirling-PDF](https://github.com/Stirling-Tools/Stirling-PDF) is a toolbox for PDF files. You merge, split, convert, compress, sign, and edit PDF files in your browser, and the files stay on your own server. -## Stirling-PDF +This stack runs Stirling-PDF with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -Stirling-PDF is a versatile, open-source toolkit that allows you to perform various PDF manipulations, such as merging, splitting, compressing, and converting PDF files. With an intuitive and user-friendly interface, Stirling-PDF simplifies complex PDF tasks, making it a valuable tool for both personal and professional use. This configuration leverages Tailscale to securely connect to your Stirling-PDF instance, protecting your sensitive document operations from unauthorized access. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | ----------------------------------------------------------------------- | +| Web interface | `https://stirlingpdf..ts.net` | +| Service port | `8080` | +| Image | `frooodle/s-pdf` | +| Data | `./stirlingpdf-data/extraConfigs` (settings and database) | +| | `./stirlingpdf-data/trainingData` (language files for text recognition) | -In this setup, the `tailscale-stirlingpdf` service runs Tailscale, which manages secure networking for the Stirling-PDF service. The `stirlingpdf` service uses the Tailscale network stack via Docker’s `network_mode: service:tailscale` configuration. This setup ensures that Stirling-PDF's interface is only accessible through the Tailscale network (or locally, if preferred), providing an extra layer of security and privacy for your PDF processing tasks. +## Before you start + +Nothing beyond the [Quick Start](../../README.md#quick-start). + +## Deviations from the standard setup + +None. + +## First run + +Open the web interface and log in with username `admin` and password `stirling`. Stirling-PDF creates this account at the first start, so change the password right after you log in. + +## Links + +- [Stirling-PDF documentation](https://docs.stirlingpdf.com/) +- [Stirling-PDF source code](https://github.com/Stirling-Tools/Stirling-PDF) diff --git a/services/subtrackr/README.md b/services/subtrackr/README.md index 87a6a263..c4046740 100644 --- a/services/subtrackr/README.md +++ b/services/subtrackr/README.md @@ -1,21 +1,30 @@ -# Subtrackr with Tailscale Sidecar Configuration +# SubTrackr -This Docker Compose configuration sets up [**Subtrackr**](https://github.com/bscott/subtrackr) with Tailscale as a sidecar container, enabling secure access to your self-hosted subscription tracking platform from anywhere on your private Tailscale network. With this setup, your Subtrackr instance remains fully private and accessible only from authorized devices. +[SubTrackr](https://github.com/bscott/subtrackr) tracks your subscriptions. It shows what you pay per month and per year and when each subscription renews. -## Subtrackr +This stack runs SubTrackr with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[**Subtrackr**](https://github.com/bscott/subtrackr) is an open-source, self-hosted web application for managing and tracking recurring subscriptions. It provides a clean, modern interface to help you monitor costs, renewal dates, and payment methods across all your services. Designed for individuals and households, Subtrackr makes it easy to stay on top of your digital and physical subscriptions without relying on third-party services. +## At a glance -## Key Features +| Item | Value | +| ------------- | ------------------------------------ | +| Web interface | `https://subtrackr..ts.net` | +| Service port | `8080` | +| Image | `ghcr.io/bscott/subtrackr` | +| Data | `./subtrackr-data/data` | -* **Centralized Subscription Management** – Keep all your recurring subscriptions organized in one place. -* **Expense Tracking** – Monitor total spending, breakdowns, and trends across services. -* **Renewal Reminders** – Stay informed with upcoming renewal and billing notifications. -* **Service Categorization** – Group subscriptions by category for clear overviews (e.g., streaming, utilities, software). -* **Payment Method Tracking** – Associate subscriptions with credit cards, bank accounts, or other payment methods. -* **Responsive Web Interface** – A simple, mobile-friendly UI for adding and reviewing subscriptions. -* **Self-Hosted & Open Source** – Run Subtrackr on your own infrastructure with Docker, ensuring privacy and data ownership. +## Before you start -## Configuration Overview +Nothing beyond the [Quick Start](../../README.md#quick-start). -In this deployment, the `tailscale-subtrackr` service runs the Tailscale client to establish a secure private network. The `subtrackr` container uses `network_mode: service:tailscale` to route all traffic through the Tailscale interface. This ensures that your subscription data, dashboards, and administration interface are only accessible via Tailscale, preventing public exposure. +## Deviations from the standard setup + +None. + +## First run + +Open the web interface. SubTrackr has no login by default, so everyone who can reach the device on your Tailnet can see and change your data. You can enable a login in the settings. + +## Links + +- [SubTrackr documentation and source code](https://github.com/bscott/subtrackr) diff --git a/services/sure/README.md b/services/sure/README.md index e271c3e7..358b4294 100644 --- a/services/sure/README.md +++ b/services/sure/README.md @@ -1,110 +1,86 @@ -# Sure with Tailscale Sidecar Configuration +# Sure -This Docker Compose configuration sets up [Sure](https://github.com/we-promise/sure) with Tailscale as a sidecar container, enabling secure, private access to your self-hosted personal finance platform over your Tailnet. With this setup, your Sure instance is **not exposed to the public internet** and is only reachable from authorized devices connected via Tailscale. +[Sure](https://sure.am) is a personal finance application and a community fork of the archived Maybe Finance project. You track bank accounts, investments, and crypto holdings and follow your net worth, with support for several currencies. -## Sure +This stack runs Sure with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[**Sure**](https://sure.am) is a self-hosted personal finance application and a community-maintained fork of the now-archived Maybe Finance project. It is an all-in-one platform for tracking bank accounts, monitoring stocks and crypto holdings, and following your overall net worth — all from a single interface with multi-currency support. +## At a glance -Sure is built on Ruby on Rails and is designed for individuals and households that want full ownership of their financial data instead of relying on cloud-hosted finance apps. It includes transaction and portfolio tracking alongside optional AI-assisted features, while remaining fully self-hostable with Docker. +| Item | Value | +| ------------- | ---------------------------------------------------------- | +| Web interface | `https://sure..ts.net` | +| Service port | `3000` | +| Images | `ghcr.io/we-promise/sure:stable` | +| | `postgres:16` | +| | `redis` | +| | `prodrigestivill/postgres-backup-local` (optional backups) | +| Data | `./app-storage` (uploaded files) | +| | `./postgres-data` (PostgreSQL database) | +| | `./redis-data` (Redis data) | +| | `./backups` (database backups) | -## Key Features +## Before you start -- 📊 Net worth tracking across all of your accounts -- 💳 Bank, credit card, and cash transaction management -- 📈 Stocks and cryptocurrency portfolio monitoring -- 💱 Multi-currency support for international finances -- 🤖 Optional AI features (chat, rules) via OpenAI integration -- 🔐 Optional OpenID Connect (OIDC) single sign-on -- 🔑 WebAuthn MFA support for passkeys and hardware security keys -- 🛡️ Tailnet-only access when paired with the included Tailscale sidecar +1. Create the data folders yourself, so that Docker does not create them as user `root`: -## Configuration Overview + ```bash + mkdir -p config ts/state app-storage postgres-data redis-data backups + ``` -Sure is a **multi-container application**. This stack runs the following services on a dedicated `sure_net` Docker bridge network alongside the Tailscale sidecar: +2. Set these values in `.env`: -- **web** – the main Rails web application (`ghcr.io/we-promise/sure:stable`), serving the Sure UI on port `3000`. -- **worker** – a Sidekiq background worker (same image, run with `bundle exec sidekiq`) that processes asynchronous jobs. -- **db** – a PostgreSQL 16 database storing all Sure data. -- **redis** – a Redis instance used as the Sidekiq queue and cache. -- **backup** *(optional, behind the `backup` profile)* – a scheduled PostgreSQL backup container. + - **`SECRET_KEY_BASE`.** Required and empty by default. Generate a value with `openssl rand -hex 64`. + - **`POSTGRES_USER`, `POSTGRES_PASSWORD`, and `POSTGRES_DB`.** The defaults `sure_user`, `sure_password`, and `sure_production` are samples. Change them before you use Sure with real data. + - **`DB_HOST`, `REDIS_URL`, and `POSTGRES_HOST`.** Leave these as they are, unless you change the IP addresses of the network that the deviations describe. -The `tailscale` service authenticates to your Tailnet and provides the private network endpoint. The `web` and `worker` containers share the Tailscale container's network namespace using Docker's `network_mode: service:tailscale` pattern, so they reach the Tailnet directly and publish no ports to the host. +## Deviations from the standard setup -### Hybrid networking +- **Several application containers.** The stack has no `application` service. It runs `web` (the web interface), `worker` (background jobs with Sidekiq), `db` (PostgreSQL), `redis`, and the optional `backup`. +- **Two networks.** `web` and `worker` use the network of the `tailscale` container. `db`, `redis`, and `backup` use a separate Docker network, `sure_net`, with fixed IP addresses. The `tailscale` container is attached to that network as well, so that `web` and `worker` can reach the database and Redis. +- **MagicDNS is enabled.** The stack sets `TS_ACCEPT_DNS=true`, which replaces Docker's DNS for `web` and `worker`. They cannot resolve the names `db` and `redis`, so `.env` gives them the fixed IP addresses instead (`DB_HOST=172.28.0.10` and `REDIS_URL=redis://172.28.0.11:6379/1`). +- **HTTPS settings.** `.env` sets `RAILS_FORCE_SSL=true` and `RAILS_ASSUME_SSL=true`. Tailscale Serve provides HTTPS and forwards plain HTTP to port `3000`, and `RAILS_ASSUME_SSL` tells Sure that the connection is secure. +- **Data folders.** The data is in `./app-storage`, `./postgres-data`, `./redis-data`, and `./backups`, not in a `./sure-data` folder. -This stack uses a hybrid networking approach so that Tailscale and Sure's support containers can coexist: +## First run -- `web` and `worker` use `network_mode: service:tailscale` (Tailnet-only). -- `db`, `redis`, and `backup` run on the `sure_net` bridge network with static IPs. -- The `tailscale` container is attached to `sure_net` so its network namespace can reach the database and Redis. +Open the web interface and select **create your account**. Sure has no default login. The first account that you create is yours. -Because **MagicDNS is enabled** (`TS_ACCEPT_DNS=true`), Tailscale overrides Docker's embedded DNS inside the `web`/`worker` namespace. This means `web` and `worker` **cannot resolve container names** like `db` or `redis`, so they connect to the database and Redis using their static IPs (`DB_HOST=172.28.0.10`, `REDIS_URL=redis://172.28.0.11:6379/1`) defined in the `.env` file. The `backup` container sits directly on `sure_net`, so it can still use Docker DNS (`POSTGRES_HOST=db`). +## Configuration -## Before You Start +### Database backups -Review and edit the `.env` file before launching the stack. Several values must be set correctly for the app to run and to remain secure: - -- **`TS_AUTHKEY`** – required; generate an auth key at . -- **`SECRET_KEY_BASE`** – required and **empty by default**. Generate a unique value with `openssl rand -hex 64` and paste it. -- **`POSTGRES_USER` / `POSTGRES_PASSWORD` / `POSTGRES_DB`** – the defaults (`sure_user` / `sure_password` / `sure_production`) are placeholders and should be changed before deploying for production use. -- **`DB_HOST`, `REDIS_URL`, `POSTGRES_HOST`** – leave as-is unless you change the static IPs or network layout described above. -- **`TZ`** – set to your local time zone. - -### Bind mount directories - -The compose file bind-mounts several host directories. Pre-create them so Docker does not create them as root-owned: +The `backup` container makes scheduled backups of the database. It only runs when you start the stack with the `backup` profile: ```bash -mkdir -p config ts/state app-storage postgres-data redis-data backups +docker compose --profile backup up -d ``` -## HTTPS / SSL Settings - -The `.env` ships with `RAILS_FORCE_SSL=true` and `RAILS_ASSUME_SSL=true`. Because Tailscale Serve terminates TLS in front of the app, `RAILS_ASSUME_SSL=true` is what tells Rails the connection is secure even though Serve forwards to it over plain HTTP on port `3000`. If you access Sure directly over HTTP through the Tailnet and encounter redirect issues, set both values back to `false`. - -## Troubleshooting - -If stock price or exchange-rate syncs fail with `Failed to open TCP connection to fc.yahoo.com`, DNS is likely resolving Yahoo Finance to IPv6 first, which the container can't reach. Upstream forces IPv4 DNS (`dns: [8.8.8.8, 1.1.1.1]`) on `web`/`worker`; this stack omits it because their DNS is handled by Tailscale (MagicDNS). For the recommended workarounds, see the note in the [Sure Docker self-hosting guide](https://github.com/we-promise/sure/blob/main/docs/hosting/docker.md). - -## Optional Integrations +The backups are in `./backups`. `SCHEDULE`, `BACKUP_KEEP_DAYS`, `BACKUP_KEEP_WEEKS`, and `BACKUP_KEEP_MONTHS` in `.env` set the schedule and how long backups are kept. -### OpenAI (AI features) +### AI features -Sure can use OpenAI for AI-powered features such as chat and rules. Set `OPENAI_ACCESS_TOKEN` in `.env` to enable it. **Enabling OpenAI will incur costs on your OpenAI account**, so set appropriate spend limits before adding it. See the [Sure AI documentation](https://github.com/we-promise/sure/blob/main/docs/hosting/ai.md). +Sure can use OpenAI for chat and rules. Set `OPENAI_ACCESS_TOKEN` in `.env` to enable it. This causes costs on your OpenAI account, so set a spending limit first. See the [Sure AI documentation](https://github.com/we-promise/sure/blob/main/docs/hosting/ai.md). -### OpenID Connect (OIDC) +### OpenID Connect -Sure supports OIDC for external authentication providers such as Google, GitHub, Keycloak, Authentik, Okta, or Azure AD. Fill in `OIDC_ISSUER`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET`, and `OIDC_REDIRECT_URI` in the `.env` file to enable it. The redirect URI should follow the pattern `https:///auth/openid_connect/callback`. See the [Sure OIDC documentation](https://github.com/we-promise/sure/blob/main/docs/hosting/oidc.md). +Sure can use an OpenID Connect provider for the login, such as Keycloak, Authentik, or [Pocket ID](../pocket-id/). Set `OIDC_ISSUER`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET`, and `OIDC_REDIRECT_URI` in `.env`. The redirect address has the form `https://sure..ts.net/auth/openid_connect/callback`. See the [Sure OIDC documentation](https://github.com/we-promise/sure/blob/main/docs/hosting/oidc.md). -### WebAuthn MFA (passkeys) +### Passkeys -If you enable passkeys, Touch ID, Windows Hello, or hardware security keys as MFA credentials, pin the WebAuthn relying party settings (`WEBAUTHN_RP_ID` and `WEBAUTHN_ALLOWED_ORIGINS`) in your environment before registering any passkeys. See the [WebAuthn configuration guide](https://github.com/we-promise/sure/blob/main/docs/hosting/webauthn.md). +If you use passkeys or security keys as a second factor, set `WEBAUTHN_RP_ID` and `WEBAUTHN_ALLOWED_ORIGINS` before anyone registers a passkey. See the [WebAuthn configuration guide](https://github.com/we-promise/sure/blob/main/docs/hosting/webauthn.md). -## Usage Notes - -Start the core stack with: - -```bash -docker compose up -d -``` +## Troubleshooting -On first launch, open the Sure URL on your Tailnet and click **create your account** to register the initial user. There are no default admin credentials — the first account you create becomes your login. +### Sync of stock prices or exchange rates fails -To run the optional scheduled database backups, include the backup profile: +If a sync fails with `Failed to open TCP connection to fc.yahoo.com`, DNS probably returns an IPv6 address for Yahoo Finance first, which the container cannot reach. The upstream Compose file forces IPv4 DNS servers for `web` and `worker`. This stack leaves that out, because Tailscale handles their DNS. See the note in the [Sure Docker guide](https://github.com/we-promise/sure/blob/main/docs/hosting/docker.md) for workarounds. -```bash -docker compose --profile backup up -d -``` +### Redirect loop without HTTPS -Backups are written to the `./backups` directory by default; adjust the retention settings (`SCHEDULE`, `BACKUP_KEEP_DAYS`, `BACKUP_KEEP_WEEKS`, `BACKUP_KEEP_MONTHS`) in `.env` as needed. +If you open Sure over plain HTTP and get redirect errors, set `RAILS_FORCE_SSL` and `RAILS_ASSUME_SSL` in `.env` to `false`. -## References +## Links -- [Sure Website](https://sure.am) -- [Sure GitHub Repository](https://github.com/we-promise/sure) -- [Sure Docker Self-Hosting Guide](https://github.com/we-promise/sure/blob/main/docs/hosting/docker.md) -- [Sure OIDC Documentation](https://github.com/we-promise/sure/blob/main/docs/hosting/oidc.md) -- [Sure AI Documentation](https://github.com/we-promise/sure/blob/main/docs/hosting/ai.md) -- [Sure WebAuthn Documentation](https://github.com/we-promise/sure/blob/main/docs/hosting/webauthn.md) -- [Tailscale Docker Documentation](https://tailscale.com/kb/1282/docker) +- [Sure Docker guide](https://github.com/we-promise/sure/blob/main/docs/hosting/docker.md) +- [Sure website](https://sure.am) +- [Sure source code](https://github.com/we-promise/sure) diff --git a/services/swingmx/README.md b/services/swingmx/README.md index a365b8d2..2942c1d4 100644 --- a/services/swingmx/README.md +++ b/services/swingmx/README.md @@ -1,35 +1,32 @@ -# Swing Music with Tailscale Sidecar Configuration +# Swing Music -This Docker Compose configuration sets up **Swing Music** with a Tailscale sidecar container, enabling secure access to your self-hosted music streaming server over your private Tailscale network. With this setup, your Swing Music instance remains **private and accessible only from authorized devices on your Tailnet**. +[Swing Music](https://swingmx.com/) is a music player and streaming server for your own audio files, with a web interface that resembles the commercial streaming services. -## Swing Music +This stack runs Swing Music with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[**Swing Music**](https://github.com/swingmx/swingmusic) is a fast, beautiful, self-hosted music player and streaming server for your **local audio collection**. It offers a modern browser-based interface to browse, search, and stream your own music—without relying on third-party cloud services or exposing your library publicly. +## At a glance -## Key Features +| Item | Value | +| ------------- | ------------------------------------------------------ | +| Web interface | `https://swingmusic..ts.net` | +| Service port | `1970` | +| Image | `ghcr.io/swingmx/swingmusic` | +| Data | `./swingmusic-data/app/config` (settings and database) | +| | The folder that you mount at `/music` (your music) | -- 🎧 **Daily Mixes** – Automatically generated mixes based on your listening habits. -- 🎼 **Local Music Streaming** – Stream your own audio files directly from your server. -- 🧹 **Metadata Normalization** – Keeps your music library clean and consistent. -- 💿 **Album Version Grouping** – Smart grouping of deluxe, remastered, or alternate album versions. -- 🧭 **Related Artists & Albums** – Discover similar music within your own library. -- 📁 **Folder-Based Browsing** – Explore your collection by folder structure. -- 📝 **Playlist Management** – Create and manage playlists from the web interface. -- ✨ **Modern Web UI** – Clean, fast, and responsive interface for desktop and mobile browsers. -- 🔎 **Fuzzy Search & Duplicate Detection** – Quickly find music and handle duplicates. +## Before you start -## Why Self-Host? +Replace `/path/to/music` in `compose.yaml` with the absolute path of the folder on the Docker host that holds your music. -Self-hosting Swing Music gives you **full ownership of your music library**, complete privacy, and independence from subscription-based streaming services. When paired with Tailscale, your music server is never exposed to the public internet, yet remains securely accessible from anywhere. +## Deviations from the standard setup -## Configuration Overview +- **Device name.** `SERVICE` in `.env` is `swingmusic`, which differs from the name of this directory. -In this deployment, a **Tailscale sidecar container** (for example `tailscale-swingmusic`) runs the Tailscale client and joins your private Tailscale network. The main `swingmusic` service uses: +## First run -```plain -network_mode: service:tailscale -``` +Open the web interface and follow the setup. You create your account and select `/music` as your music folder. -This configuration routes all traffic through the Tailscale interface, ensuring the Swing Music web UI and streaming endpoints are accessible **only via your Tailscale network**. This keeps your music library secure while allowing seamless access from all your trusted devices. +## Links -Before starting the stack, replace `/path/to/music` in `compose.yaml` with the absolute host directory that contains your music library. +- [Swing Music documentation](https://swingmx.com/guide/introduction.html) +- [Swing Music source code](https://github.com/swingmx/swingmusic) diff --git a/services/tailscale-app-connector-node/README.md b/services/tailscale-app-connector-node/README.md index e53d8e55..7afb006c 100644 --- a/services/tailscale-app-connector-node/README.md +++ b/services/tailscale-app-connector-node/README.md @@ -1,16 +1,38 @@ -# Tailscale App Connector Node Configuration +# Tailscale App Connector -This Docker Compose configuration sets up a Tailscale an App Connector Node, allowing devices in your Tailscale network to route their traffic securely through this node to internet services. +A Tailscale [app connector](https://tailscale.com/docs/features/app-connectors/how-to/setup) routes Tailnet traffic for selected applications through itself. Users and devices reach these applications by domain name instead of by IP address. -## Tailscale App Connector Node +This stack runs only the Tailscale container from [the standard setup](../../documentation/standard-setup.md), configured as an app connector. -App connectors let you route Tailscale network (known as a tailnet) traffic to your software as a service (SaaS), cloud, and self-hosted applications, letting users and devices on the tailnet access applications by domain names instead of IP addresses. You can also incorporate monitoring, optimization, security, and reliability into your app connector setup. [See the App Connector documents for more information:](https://tailscale.com/docs/features/app-connectors/how-to/setup) +## At a glance -## Configuration Overview +| Item | Value | +| -------------- | --------------------- | +| Web interface | None | +| Tailnet device | `app-connector` | +| Image | `tailscale/tailscale` | +| Data | `./ts/state` | -In this setup, the `tailscale` service runs a Tailscale container configures it as an App Connector Node. +## Before you start -- **TS_AUTHKEY**: This environment variable in the .env file is where you insert your Tailscale authentication key. -- **TS_EXTRA_ARGS**: The `--advertise-connector` flag is used to designate this container as a App Connector Node within your Tailscale network. -- **Sysctls**: The system controls `net.ipv4.ip_forward` and `net.ipv6.conf.all.forwarding` are enabled to allow IP forwarding, which is necessary for routing traffic through the Exit Node. -- **Network Mode**: The `bridge` network mode is used to create a virtual network interface for the container, enabling it to handle traffic routing. +An app connector needs a tag and matching rules in your Tailnet policy. Follow the [app connector setup guide](https://tailscale.com/docs/features/app-connectors/how-to/setup) first: + +1. Create a tag for the connector and add the `tagOwners`, `autoApprovers`, and `grants` entries from the guide to your Tailnet policy. +2. Give the device that tag. Create the auth key for `TS_AUTHKEY` with the tag, or add `--advertise-tags=tag:` to `TS_EXTRA_ARGS` in `compose.yaml`. + +## Deviations from the standard setup + +- **No application container.** The stack has no `application` service, no Tailscale Serve configuration, and no `./config` folder. +- **Connector flag.** `TS_EXTRA_ARGS=--advertise-connector` offers the device as an app connector to your Tailnet. +- **IP forwarding.** The `sysctls` block enables IPv4 and IPv6 forwarding in the container, which an app connector requires. +- **Bridge network.** The container uses `network_mode: bridge`, so forwarded traffic leaves through the Docker host. +- **DNS server.** The `dns` block is active and uses `DNS_SERVER` from `.env`. + +## First run + +Add your applications on the **Apps** page of the Tailscale admin console and assign them to the tag of the connector. + +## Links + +- [Tailscale app connector setup](https://tailscale.com/docs/features/app-connectors/how-to/setup) +- [Tailscale in Docker](https://tailscale.com/kb/1282/docker) diff --git a/services/tailscale-exit-node/README.md b/services/tailscale-exit-node/README.md index 66e705e7..6c61efc2 100644 --- a/services/tailscale-exit-node/README.md +++ b/services/tailscale-exit-node/README.md @@ -1,18 +1,37 @@ -# Tailscale Exit Node Configuration +# Tailscale Exit Node -This Docker Compose configuration sets up a Tailscale Exit Node, allowing devices in your Tailscale network to route their internet traffic securely through this node. By configuring a Tailscale Exit Node, you can enhance the privacy and security of your internet browsing by routing traffic through a trusted network, such as your home or office, rather than relying on potentially less secure public networks. +A Tailscale [exit node](https://tailscale.com/kb/1103/exit-nodes) routes the internet traffic of other Tailnet devices through itself. Devices that use it reach the internet from the network of the Docker host, for example your home or office. -## Tailscale Exit Node +This stack runs only the Tailscale container from [the standard setup](../../documentation/standard-setup.md), configured as an exit node. -A Tailscale Exit Node is a device within your Tailscale network that other devices can use as a gateway to the internet. By setting up an Exit Node, you ensure that all traffic from connected devices is routed through a secure and private network, benefiting from the encryption and privacy that Tailscale provides. This configuration leverages Docker to easily deploy and manage a Tailscale Exit Node, offering a straightforward solution to secure your internet traffic. +## At a glance -## Configuration Overview +| Item | Value | +| -------------- | --------------------- | +| Web interface | None | +| Tailnet device | `exit-node` | +| Image | `tailscale/tailscale` | +| Data | `./ts/state` | -In this setup, the `tailscale` service runs a Tailscale container configured as an Exit Node. The key configurations include: +## Before you start -- **TS_AUTHKEY**: This environment variable is where you insert your Tailscale authentication key. -- **TS_EXTRA_ARGS**: The `--advertise-exit-node` flag is used to designate this container as an Exit Node within your Tailscale network. -- **Sysctls**: The system controls `net.ipv4.ip_forward` and `net.ipv6.conf.all.forwarding` are enabled to allow IP forwarding, which is necessary for routing traffic through the Exit Node. -- **Network Mode**: The `bridge` network mode is used to create a virtual network interface for the container, enabling it to handle traffic routing. +Nothing beyond the [Quick Start](../../README.md#quick-start). -This configuration ensures that the Tailscale Exit Node is set up correctly, allowing devices connected to your Tailscale network to securely route their internet traffic through this node. +## Deviations from the standard setup + +- **No application container.** The stack has no `application` service, no Tailscale Serve configuration, and no `./config` folder. +- **Exit node flag.** `TS_EXTRA_ARGS=--advertise-exit-node` offers the device as an exit node to your Tailnet. +- **IP forwarding.** The `sysctls` block enables IPv4 and IPv6 forwarding in the container, which an exit node on Linux requires. +- **Bridge network.** The container uses `network_mode: bridge`, so forwarded traffic leaves through the Docker host. +- **DNS server.** The `dns` block is active and uses `DNS_SERVER` from `.env`. + +## First run + +1. In the Tailscale admin console, open the **Machines** page and find the `exit-node` device. +2. Open its menu, select **Edit route settings**, and enable **Use as exit node**. +3. On each device that should use the exit node, select it in the Tailscale client. On Linux, run `sudo tailscale set --exit-node=`. + +## Links + +- [Tailscale exit nodes](https://tailscale.com/kb/1103/exit-nodes) +- [Tailscale in Docker](https://tailscale.com/kb/1282/docker) diff --git a/services/tailscale-subnet-router-node/README.md b/services/tailscale-subnet-router-node/README.md index 108efc49..80591004 100644 --- a/services/tailscale-subnet-router-node/README.md +++ b/services/tailscale-subnet-router-node/README.md @@ -1,17 +1,37 @@ -# Tailscale Subnet Router Node Configuration +# Tailscale Subnet Router -This Docker Compose configuration sets up a Tailscale Subnet Router Node, allowing devices in your Tailscale network to route their traffic securely through this node to a local subnet. By configuring a Tailscale Router Node, you can extend your local network of device to tailscale connected clients, such as your home or office. +A Tailscale [subnet router](https://tailscale.com/docs/features/subnet-routers) gives your Tailnet access to devices that cannot run Tailscale themselves. It forwards traffic between your Tailnet and a local network, such as your home or office network. -## Tailscale Subnet Router Node +This stack runs only the Tailscale container from [the standard setup](../../documentation/standard-setup.md), configured as a subnet router. -Subnet routers let you extend your Tailscale network (known as a tailnet) to include devices that don't or can't run the Tailscale client. They act as gateways between your tailnet and physical subnets, enabling secure access to legacy devices, entire networks, or services without installing Tailscale everywhere. This capability maintains Tailscale's security model while providing flexibility for complex network environments. +## At a glance -## Configuration Overview +| Item | Value | +| -------------- | --------------------- | +| Web interface | None | +| Tailnet device | `subnet-router` | +| Image | `tailscale/tailscale` | +| Data | `./ts/state` | -In this setup, the `tailscale` service runs a Tailscale container configures it as a Subnet Router Node. +## Before you start -- **TS_AUTHKEY**: This environment variable in the .env file is where you insert your Tailscale authentication key. -- **SUBNET_ROUTES**: This setting defined in .env file allows the user to set the desired route. More information can be found on the [Tailscale subnet router documents page.](https://tailscale.com/docs/features/subnet-routers) -- **TS_EXTRA_ARGS**: The `--advertise-routes` flag is used to designate this container as a Subnet Router Node within your Tailscale network. -- **Sysctls**: The system controls `net.ipv4.ip_forward` and `net.ipv6.conf.all.forwarding` are enabled to allow IP forwarding, which is necessary for routing traffic through the Exit Node. -- **Network Mode**: The `bridge` network mode is used to create a virtual network interface for the container, enabling it to handle traffic routing. +Set `SUBNET_ROUTES` in `.env` to the networks that the router should offer, as a comma-separated list. The default `10.1.234.0/24` is an example. + +## Deviations from the standard setup + +- **No application container.** The stack has no `application` service, no Tailscale Serve configuration, and no `./config` folder. +- **Advertised routes.** `TS_ROUTES` passes the value of `SUBNET_ROUTES` to Tailscale, which offers these routes to your Tailnet. +- **IP forwarding.** The `sysctls` block enables IPv4 and IPv6 forwarding in the container, which a subnet router on Linux requires. +- **Bridge network.** The container uses `network_mode: bridge`, so it reaches the local network through the Docker host. +- **DNS server.** The `dns` block is active and uses `DNS_SERVER` from `.env`. + +## First run + +1. In the Tailscale admin console, open the **Machines** page and select the `subnet-router` device. +2. In the **Subnets** section, select **Edit**. Under **Subnet routes**, select the routes to approve and select **Save**. +3. Linux devices do not use subnet routes by default. Run `sudo tailscale set --accept-routes` on each Linux device that should use them. + +## Links + +- [Tailscale subnet routers](https://tailscale.com/docs/features/subnet-routers) +- [Tailscale in Docker](https://tailscale.com/kb/1282/docker) diff --git a/services/tandoor/README.md b/services/tandoor/README.md index d6136245..98da2d31 100644 --- a/services/tandoor/README.md +++ b/services/tandoor/README.md @@ -1,18 +1,40 @@ -# Tandoor Recipes with Tailscale Sidecar Configuration +# Tandoor Recipes -This Docker Compose configuration sets up [**Tandoor Recipes**](https://github.com/TandoorRecipes/recipes) with Tailscale as a sidecar container, which enables a secure access to your personal recipe and meal planning platform from your Tailscale network. As with all other services inside this repository, your service stays fully private and accessible only to your authorized devices. +[Tandoor Recipes](https://tandoor.dev/) manages your recipes. It also plans your meals and builds your shopping lists. -## Tandoor Recipes +This stack runs Tandoor Recipes with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[**Tandoor Recipes**](https://github.com/TandoorRecipes/recipes) is an application for managing recipes, planning meals, building shopping lists and much much more: +## At a glance -- 🥗 **Manage your recipes** - Manage your ever growing recipe collection -- 📆 **Plan** - multiple meals for each day -- 🛒 **Shopping lists** - via the meal plan or straight from recipes -- 🪄 **use AI** to recognize images, sort recipe steps, find nutrition facts and more -- 📚 **Cookbooks** - collect recipes into books -- 👪 **Share and collaborate** on recipes with friends and family +| Item | Value | +| ------------- | --------------------------------------------------------- | +| Web interface | `https://tandoor..ts.net` | +| Service port | `9001` | +| Images | `vabene1111/recipes` | +| | `postgres:16-alpine` | +| Data | `./tandoor-data/mediafiles` (uploaded images and files) | +| | `./tandoor-data/staticfiles` (files of the web interface) | +| | `./tandoor-data/database` (PostgreSQL database) | -## Configuration Overview +## Before you start -In this setup, the `tailscale-tandoor` service runs Tailscale, which manages secure networking for the service. The `tandoor` service utilizes the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This setup ensures that tandoor's service is only accessible through the Tailscale network (or locally, if preferred), providing an extra layer of security and privacy for your service. +Set these values in `.env`: + +- **`SECRET_KEY`.** A long random value. Generate one with `base64 /dev/urandom | head -c50`. +- **`POSTGRES_PASSWORD`.** A random password of letters and digits. +- **`ALLOWED_HOSTS`.** The name of the device on your Tailnet, `tandoor..ts.net`. Tandoor answers requests for other host names with error `400`. + +## Deviations from the standard setup + +- **Extra container.** The stack runs a `database` container with PostgreSQL. It uses the network of the `tailscale` container as well, so Tandoor reaches it at `127.0.0.1`. PostgreSQL therefore also listens on port `5432` of the Tailscale IP address of the device. +- **Service port.** `TANDOOR_PORT` makes Tandoor listen on the port from `SERVICEPORT`, which is `9001`. +- **The container reads the whole `.env` file.** The `application` container loads `.env` through `env_file`. Every variable in that file, including `TS_AUTHKEY`, is therefore present in its environment. + +## First run + +The first start can take a few minutes, because Tandoor prepares its database. Then open the web interface. Tandoor sends you to the setup page, where you create the first account. + +## Links + +- [Tandoor Recipes documentation](https://docs.tandoor.dev/) +- [Tandoor Recipes source code](https://github.com/TandoorRecipes/recipes) diff --git a/services/tautulli/README.md b/services/tautulli/README.md index a8bc9bc2..10d65df6 100644 --- a/services/tautulli/README.md +++ b/services/tautulli/README.md @@ -1,11 +1,37 @@ -# Tautulli with Tailscale Sidecar Configuration +# Tautulli -This Docker Compose configuration sets up [Tautulli for Docker](https://hub.docker.com/r/linuxserver/tautulli) with Tailscale as a sidecar container to securely monitor and manage your Plex Media Server over a private Tailscale network. By integrating Tailscale in a sidecar configuration, you enhance the security and privacy of your Tautulli installation, ensuring that it is only accessible within your Tailscale network. +[Tautulli](https://tautulli.com/) monitors your Plex Media Server. It shows who watches what, keeps a history and statistics, and sends notifications. -## Tautulli +This stack runs Tautulli with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Tautulli](https://tautulli.com/) is a popular monitoring and analytics tool for Plex Media Server. It provides detailed insights into your server’s activity, including media consumption, user activity, and server health. Tautulli allows you to generate reports, send notifications, and manage users, making it an essential tool for Plex server administrators. This configuration leverages Tailscale to securely connect to your Tautulli interface, protecting your server's monitoring data from unauthorized access. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | ----------------------------------- | +| Web interface | `https://tautulli..ts.net` | +| Service port | `8181` | +| Image | `lscr.io/linuxserver/tautulli` | +| Data | `./tautulli-data/app/config` | -In this setup, the tailscale-tautulli service runs Tailscale, which manages secure networking for the Tautulli service. The tautulli service utilizes the Tailscale network stack via Docker's network_mode: service:tailscale configuration. This setup ensures that Tautulli’s monitoring interface is only accessible through the Tailscale network (or locally, if preferred), providing an extra layer of security and privacy for your Plex server monitoring and management. +## Before you start + +Nothing beyond the [Quick Start](../../README.md#quick-start). + +## Deviations from the standard setup + +None. + +## First run + +Open the web interface. The setup wizard asks you to: + +1. Create a username and password for Tautulli. +2. Sign in with your Plex account. +3. Enter the address of your Plex Media Server. To reach Plex in another stack, see the [DNS section of the standard setup](../../documentation/standard-setup.md#dns). Plex listens on port `32400`. +4. Choose the settings for activity logging and notifications. + +## Links + +- [Tautulli wiki](https://github.com/Tautulli/Tautulli/wiki) +- [Tautulli source code](https://github.com/Tautulli/Tautulli) +- [LinuxServer.io image documentation](https://docs.linuxserver.io/images/docker-tautulli/) diff --git a/services/technitium/README.md b/services/technitium/README.md index 3696b239..9b964053 100644 --- a/services/technitium/README.md +++ b/services/technitium/README.md @@ -1,11 +1,44 @@ -# Technitium DNS server with Tailscale Sidecar Configuration +# Technitium DNS Server -This Docker Compose configuration sets up a [Technitium DNS Server](https://github.com/TechnitiumSoftware/DnsServer) with Tailscale as a sidecar container ...... +[Technitium DNS Server](https://technitium.com/dns/) is a DNS server for your network. It resolves names itself or through forwarders, blocks advertisements, and hosts your own DNS zones. -## Technitium +This stack runs Technitium DNS Server with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Technitium DNS Server](https://github.com/TechnitiumSoftware/DnsServer) information about Technitium... +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | ------------------------------------------------------------------------------------------ | +| Web interface | `https://technitium..ts.net` | +| Service port | `5380` | +| DNS | Port `53` (TCP and UDP) on the Tailscale IP address of `technitium` and on the Docker host | +| Image | `technitium/dns-server` | +| Data | None on the host, see the deviations | -In this setup, the Technitium Service runs on Tailscale, which manages secure networking for the Technitium DNS Services. The `Technitium` utilizes the Tailscale network stack via Docker's `network_mode: technitium:` configuration. This setup ensures that Technitium's Technitium is only accessible through the Tailscale network (or locally, if preferred. Modifications nescsary), providing an extra layer of security and privacy for your Technitium. +## Before you start + +- **Set the administrator password.** Change `ADMIN_PASSWORD` in `.env`. The default is `ChangeME`. Technitium reads it only at the first start. +- **Free port 53.** The stack publishes port `53` on the Docker host. On a host that runs `systemd-resolved`, this port is in use. See [Free up port 53 on the Docker host](../../documentation/free-up-port-53.md). +- **Choose the forwarders.** `DNS_SERVER1` and `DNS_SERVER2` in `.env` set the DNS servers that Technitium forwards to. + +## Deviations from the standard setup + +- **Published host ports.** The `ports` block is active. It publishes the web interface on port `5380`, DNS on port `53`, DNS-over-TLS and DNS-over-QUIC on port `853`, and DNS-over-HTTPS on port `443` of the Docker host. Devices in your local network can therefore reach Technitium without Tailscale. Remove the lines that you do not need. +- **Settings are not stored on the host.** Technitium keeps its settings and zones in `/etc/dns` in the container. The stack mounts `./technitium-data/app/config` at `/config`, which Technitium does not use. Your settings are lost when the container is recreated, for example after an image update. Back up your settings in the web interface before you update. +- **Settings through environment variables.** `compose.yaml` sets the server name, recursion, and forwarders. Technitium reads these variables only at the first start, when it has no configuration yet. + +## First run + +1. Open the web interface and log in with username `admin` and the password from `ADMIN_PASSWORD`. +2. Point your devices or your router at the IP address of the Docker host as DNS server. + +## Configuration + +### Use Technitium as the DNS server of your Tailnet + +In the Tailscale admin console, open the **DNS** page. Add the Tailscale IP address of the `technitium` device as a custom nameserver and enable **Override DNS servers**. + +## Links + +- [Technitium DNS Server help](https://technitium.com/dns/help.html) +- [Technitium DNS Server source code](https://github.com/TechnitiumSoftware/DnsServer) +- [Docker environment variables](https://github.com/TechnitiumSoftware/DnsServer/blob/master/DockerEnvironmentVariables.md) diff --git a/services/tracktor/README.md b/services/tracktor/README.md index b6e6934c..64e5e4fe 100644 --- a/services/tracktor/README.md +++ b/services/tracktor/README.md @@ -1,40 +1,33 @@ -# Tracktor with Tailscale Sidecar Configuration +# Tracktor -This Docker Compose configuration sets up **Tracktor** with a **Tailscale sidecar** container, enabling secure access to your self-hosted vehicle management interface over your private Tailscale network. With this setup, your Tracktor instance remains **private and accessible only from authorized devices on your Tailnet**, keeping sensitive vehicle data, documents, and analytics off the public internet. +[Tracktor](https://github.com/javedh-dev/tracktor) manages your vehicles. You track fuel use, maintenance, insurance, and documents with their renewal dates. -## Tracktor +Tracktor is under active development and can have breaking changes. Back up your data before you update. -[**Tracktor**](https://github.com/javedh-dev/tracktor) is an open-source web application for comprehensive vehicle management. It helps you track multiple vehicles in one place, including fuel consumption, maintenance history, insurance, and regulatory documents with renewal dates. +This stack runs Tracktor with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -Tracktor is under active development and may include breaking changes. Keep regular backups of your data and validate upgrades before relying on it for critical workflows. +## At a glance -## Key Features +| Item | Value | +| ------------- | ----------------------------------- | +| Web interface | `https://tracktor..ts.net` | +| Service port | `3000` | +| Image | `ghcr.io/javedh-dev/tracktor` | +| Data | `./tracktor-data` | -- 🚗 **Vehicle Management** – Add, edit, and manage multiple vehicles, including different fuel types. -- ⛽ **Fuel Tracking** – Log fuel refills and monitor consumption and efficiency over time. -- 🧰 **Maintenance Log** – Record and review maintenance history per vehicle. -- 📄 **Document Tracking** – Track insurance, inspection, and regulatory documents with renewal dates. -- ⏰ **Reminders** – Set reminders for maintenance, renewals, and other vehicle events. -- 📊 **Dashboard & Analytics** – Visualize key metrics and upcoming renewals. -- 🔐 **User Authentication** – Username/password auth with session management. -- 🎛️ **Feature Toggles** – Enable or disable features depending on your needs. +## Before you start -## Why Self-Host? +Set `TS_TAILNET` in `.env` to your Tailnet name without `.ts.net`, for example `tail123abc`. `compose.yaml` builds the allowed browser origin from it, such as `https://tracktor.tail123abc.ts.net`. -A vehicle management system often contains personal and operational data such as license plate numbers, VINs, service history, and document expiration dates. Hosting this data yourself ensures you retain full ownership, avoid third-party data exposure, and can integrate it cleanly into your homelab or internal tooling. +## Deviations from the standard setup -When combined with Tailscale, Tracktor becomes a private portal accessible only to authenticated devices on your Tailnet. This significantly reduces attack surface by avoiding public port exposure, while preserving the convenience of accessing your vehicle records from anywhere. +- **Allowed origin.** `CORS_ORIGINS` in `compose.yaml` only accepts requests from the Tailnet address of the web interface. +- **Service port.** Tracktor listens on port `3000`. `SERVICEPORT` in `.env` is only the host port of the optional `ports` block. -## Configuration Overview +## First run -In this deployment, a **Tailscale sidecar container** (for example `tailscale-tracktor`) runs the Tailscale client and joins your private Tailscale network. The main `tracktor` service uses: +Open the web interface. Tracktor sends you to the registration page, where you create the first account. -```plain -network_mode: service:tailscale -``` +## Links -This configuration routes all inbound and outbound traffic through the Tailscale interface, ensuring that the Tracktor web UI is accessible **only via your Tailscale network**. - -Set `TS_TAILNET` in `.env` to your Tailnet DNS name without `.ts.net`, for example `tail123abc`. Compose appends `.ts.net` to build the allowed browser origin, such as `https://tracktor.tail123abc.ts.net`. - -If you enable the optional host port mapping, it maps `SERVICEPORT` to Tracktor's container port `3000`. +- [Tracktor documentation and source code](https://github.com/javedh-dev/tracktor) diff --git a/services/traefik/README.md b/services/traefik/README.md index 496ecbd9..63bb405b 100644 --- a/services/traefik/README.md +++ b/services/traefik/README.md @@ -1,23 +1,45 @@ -# Traefik with Tailscale Sidecar Configuration +# Traefik -This Docker Compose configuration sets up [Traefik](https://github.com/traefik/traefik) with Tailscale as a sidecar container to securely manage and route your traffic over a private Tailscale network. By integrating Tailscale, you can enhance the security and privacy of your Traefik instance, ensuring that access is restricted to devices within your Tailscale network. +[Traefik](https://traefik.io/traefik/) is a reverse proxy and load balancer. It discovers your containers through Docker and routes requests to them by rules that you set as labels. -## Traefik +This stack runs Traefik with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Traefik](https://github.com/traefik/traefik) is a modern, open-source reverse proxy and load balancer that simplifies the deployment and management of services in dynamic environments. It supports a wide range of integrations with container orchestration platforms and cloud providers, offering features like automatic HTTPS, load balancing, and monitoring. By incorporating Tailscale, your Traefik instance is safeguarded, ensuring that only authorized users and devices on your Tailscale network can access your applications and services. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | ------------------------------------------------------------------------------- | +| Web interface | `https://traefik..ts.net` (routes to your services, see the first run) | +| Service port | `80` | +| Images | `traefik` | +| | `yeasy/simple-web` (sample site) | +| Data | `./traefik-data/log` (Traefik log and access log) | -In this setup, the `tailscale-traefik` service runs Tailscale, which manages secure networking for Traefik. The `traefik_proxy` service uses Docker's `network_mode: service:tailscale` configuration. Traefik reads its static configuration from the `command:` flags in `compose.yaml`. Traefik ignores these flags when it finds a static configuration file, so edit the flags instead of adding a `traefik.yml` file. +## Before you start -The Traefik health check calls the ping endpoint, so keep the `--ping=true` flag. Traefik routes only to containers that Docker reports as healthy. The `simpleweb` sample therefore becomes reachable only after its first health check passes. +Nothing beyond the [Quick Start](../../README.md#quick-start). -## Tailnet Access +## Deviations from the standard setup -Tailscale Serve listens on port 443 of the Tailnet address, terminates HTTPS, and forwards requests to Traefik's `web` entrypoint on port 80. Do not add a Traefik entrypoint on port 443. Traefik shares the network of the Tailscale container, so the port is already in use. Traefik then exits, and the container restarts in a loop. +- **Published host port.** The `ports` block is active and publishes port `80` of the Docker host. Devices in your local network can therefore reach Traefik without Tailscale. +- **Service name.** The application service is called `traefik_proxy`, not `application`. +- **Docker socket.** Traefik mounts `/var/run/docker.sock` to discover containers and their labels. +- **Configuration through flags.** The `command` block in `compose.yaml` is the static configuration. Traefik ignores these flags when it finds a static configuration file, so edit the flags and do not add a `traefik.yml` file. +- **Sample site.** The stack runs a `simpleweb` container with routing labels as an example. Replace it with your own services. +- **Only port 80.** Tailscale Serve listens on port `443` of the Tailnet address and forwards to the `web` entrypoint of Traefik on port `80`. Do not add a Traefik entrypoint on port `443`. Traefik shares the network of the `tailscale` container, where that port is in use, so Traefik would exit and restart in a loop. +- **Health check.** The health check calls the ping endpoint, so keep the `--ping=true` flag. Traefik only routes to containers that Docker reports as healthy, so the sample site is reachable only after its first health check passes. -Requests through the Tailnet arrive with the host name `..ts.net`. The sample routers match `traefik.domain.local` and `simpleweb.domain.local`, so Traefik answers `404` over the Tailnet. Change a `Host()` rule to the Tailnet name to reach that router through Tailscale Serve. +## First run + +Requests through your Tailnet arrive with the host name `traefik..ts.net`. The sample routers match `traefik.domain.local` and `simpleweb.domain.local`, so Traefik answers `404` over the Tailnet at first. + +Change a `Host()` rule in the labels in `compose.yaml` to `traefik..ts.net` and restart the stack. That router is then reachable at `https://traefik..ts.net`. ## Troubleshooting -Traefik writes its log to `./${SERVICE}-data/log/traefik.log`, so `docker logs app-traefik` stays empty. Read that file when the container restarts or a router does not work. +Traefik writes its log to `./traefik-data/log/traefik.log`, so `docker logs` shows nothing for the Traefik container. Read that file when the container restarts or a router does not work. + +## Links + +- [Traefik documentation](https://doc.traefik.io/traefik/) +- [Traefik Docker provider](https://doc.traefik.io/traefik/providers/docker/) +- [Traefik source code](https://github.com/traefik/traefik) diff --git a/services/transmute/README.md b/services/transmute/README.md index c4f09711..38326857 100644 --- a/services/transmute/README.md +++ b/services/transmute/README.md @@ -1,33 +1,34 @@ -# Transmute with Tailscale Sidecar Configuration +# Transmute -This Docker Compose configuration sets up **Transmute** with a Tailscale sidecar container, allowing you to securely access your instance over your private Tailnet. With this setup, Transmute remains private by default and is only accessible from devices authenticated to your Tailscale network. +[Transmute](https://github.com/transmute-app/transmute) converts and compresses files, such as images, video, audio, and documents. It has a web interface and an API. -## Transmute +This stack runs Transmute with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[**Transmute**](https://github.com/transmute-app/transmute) is an open-source file conversion and transformation service designed to handle a wide variety of document, media, and data format conversions through a clean API and web interface. It is particularly useful for workflows that require automated or repeatable transformations between formats. +## At a glance -Running Transmute behind Tailscale ensures that your file processing pipelines and potentially sensitive data remain secure, without exposing the service publicly. +| Item | Value | +| ------------- | ------------------------------------ | +| Web interface | `https://transmute..ts.net` | +| Service port | `3313` | +| Image | `ghcr.io/transmute-app/transmute` | +| Data | `./transmute-data` | -## Key Features +## Before you start -- Convert files between multiple formats (documents, images, and more) -- API-first design for automation and integrations -- Web interface for manual conversions -- Lightweight and container-friendly deployment -- Self-hosted with full control over your data +Nothing beyond the [Quick Start](../../README.md#quick-start). -## Configuration Overview +## Deviations from the standard setup -In this setup, the `tailscale-transmute` service runs Tailscale and manages secure connectivity to your Tailnet. The `transmute` container shares the same network stack using Docker’s `network_mode: service:tailscale`. +None. -## Service Notes / Gotchas +## First run -- Some conversions may require additional system dependencies depending on formats used -- Initial startup may take longer if Transmute initializes processing tools -- Ensure sufficient CPU and memory for heavy conversions +Open the web interface and create the first account. -## Useful Links +## Configuration -- GitHub Repository: -- Tailscale Auth Keys: -- Tailscale Serve Docs: +Large conversions need a lot of CPU and memory. Give the Docker host enough of both when you convert video. + +## Links + +- [Transmute documentation and source code](https://github.com/transmute-app/transmute) diff --git a/services/uptime-kuma/README.md b/services/uptime-kuma/README.md index 1b2facfb..3c788eb4 100644 --- a/services/uptime-kuma/README.md +++ b/services/uptime-kuma/README.md @@ -1,11 +1,33 @@ -# Uptime Kuma with Tailscale Sidecar Configuration +# Uptime Kuma -This Docker Compose configuration sets up [Uptime Kuma](https://github.com/louislam/uptime-kuma) with Tailscale as a sidecar container to securely monitor your services and websites over a private Tailscale network. By using Tailscale in a sidecar configuration, you can enhance the security and privacy of your monitoring dashboard, ensuring that it is only accessible within your Tailscale network. +[Uptime Kuma](https://github.com/louislam/uptime-kuma) monitors your websites and services. It checks them at an interval, shows their uptime, and sends a notification when one is down. -## Uptime Kuma +This stack runs Uptime Kuma with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Uptime Kuma](https://github.com/louislam/uptime-kuma) is a self-hosted monitoring tool that allows you to keep track of the uptime and performance of your websites, APIs, and services. With a sleek and user-friendly interface, Uptime Kuma provides real-time monitoring, notifications, and detailed reports to help you maintain the reliability of your infrastructure. This configuration leverages Tailscale to securely connect to your Uptime Kuma dashboard, protecting your monitoring data from unauthorized access. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | -------------------------------------- | +| Web interface | `https://uptime-kuma..ts.net` | +| Service port | `3001` | +| Image | `louislam/uptime-kuma:2` | +| Data | `./uptime-kuma-data/uptime-kuma-data` | -In this setup, the `tailscale-uptimekuma` service runs Tailscale, which manages secure networking for the Uptime Kuma service. The `uptimekuma` service uses the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This setup ensures that Uptime Kuma's monitoring dashboard is only accessible through the Tailscale network (or locally, if preferred), providing an extra layer of security and privacy for your monitoring solution. +## Before you start + +Nothing beyond the [Quick Start](../../README.md#quick-start). + +## Deviations from the standard setup + +- **Docker socket.** Uptime Kuma mounts `/var/run/docker.sock` read-only, so that it can monitor the containers on the Docker host. Remove the line if you do not use this monitor type. + +## First run + +1. Open the web interface. Uptime Kuma first asks which database to use. SQLite needs no further settings. +2. Create the administrator account. +3. Add your first monitor. To monitor a service in another stack, see the [DNS section of the standard setup](../../documentation/standard-setup.md#dns). + +## Links + +- [Uptime Kuma wiki](https://github.com/louislam/uptime-kuma/wiki) +- [Uptime Kuma source code](https://github.com/louislam/uptime-kuma) diff --git a/services/vaultwarden/README.md b/services/vaultwarden/README.md index f63339da..b739dc2f 100644 --- a/services/vaultwarden/README.md +++ b/services/vaultwarden/README.md @@ -1,11 +1,39 @@ -# Vaultwarden with Tailscale Sidecar Configuration +# Vaultwarden -This Docker Compose configuration sets up [Vaultwarden](https://github.com/dani-garcia/vaultwarden) with Tailscale as a sidecar container to securely manage and access your password manager over a private Tailscale network. By using Tailscale in a sidecar configuration, you can enhance the security and privacy of your Vaultwarden instance, ensuring that it is only accessible within your Tailscale network. +[Vaultwarden](https://github.com/dani-garcia/vaultwarden) is a password manager server that works with the Bitwarden apps and browser extensions. -## Vaultwarden +This stack runs Vaultwarden with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Vaultwarden](https://github.com/dani-garcia/vaultwarden) is an open-source, self-hosted alternative to Bitwarden, a popular password manager. Vaultwarden allows you to securely store and manage your passwords, notes, and other sensitive data. This configuration leverages Tailscale to securely connect to your Vaultwarden instance, ensuring that your passwords and sensitive information are protected from unauthorized access and that your instance is accessible only via your private Tailscale network. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | -------------------------------------- | +| Web interface | `https://vaultwarden..ts.net` | +| Service port | `80` | +| Image | `vaultwarden/server` | +| Data | `./vaultwarden-data/vw-data` | -In this setup, the `tailscale-vaultwarden` service runs Tailscale, which manages secure networking for the Vaultwarden service. The `vaultwarden` service uses the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This setup ensures that Vaultwarden’s web interface and API are only accessible through the Tailscale network (or locally, if preferred), providing an extra layer of security and privacy for your self-hosted password manager. +## Before you start + +Nothing beyond the [Quick Start](../../README.md#quick-start). + +## Deviations from the standard setup + +None. + +## First run + +1. Open the web interface and select **Create account**. +2. Registration is open to everyone who can reach the device on your Tailnet. After you created your accounts, set `SIGNUPS_ALLOWED` to `"false"` in `compose.yaml` and restart the stack. +3. In the Bitwarden apps and browser extensions, choose a self-hosted server and enter `https://vaultwarden..ts.net`. The device must be connected to your Tailnet. + +## Configuration + +### Admin page + +The admin page at `/admin` is disabled by default. To enable it, add an `ADMIN_TOKEN` to the `environment` block of `compose.yaml`. See [Enabling admin page](https://github.com/dani-garcia/vaultwarden/wiki/Enabling-admin-page). + +## Links + +- [Vaultwarden wiki](https://github.com/dani-garcia/vaultwarden/wiki) +- [Vaultwarden source code](https://github.com/dani-garcia/vaultwarden) diff --git a/services/vikunja/README.md b/services/vikunja/README.md index 74f547a2..73a0ff87 100644 --- a/services/vikunja/README.md +++ b/services/vikunja/README.md @@ -1,34 +1,39 @@ -# Vikunja with Tailscale Sidecar Configuration +# Vikunja -This Docker Compose configuration sets up **Vikunja** with Tailscale as a sidecar container, enabling secure, private access to your task management system over your Tailnet. With this setup, your Vikunja instance is only reachable from authorized devices, keeping your tasks, projects, and personal data off the public internet. +[Vikunja](https://vikunja.io) is a to-do and project management application. It has lists, boards, Gantt charts, labels, reminders, and recurring tasks, and you can share projects with others. -## Vikunja +This stack runs Vikunja with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[Vikunja](https://vikunja.io) is an open-source, self-hosted task management and to-do list application designed as a privacy-focused alternative to tools like Todoist, Trello, and Asana. It supports projects, tasks, labels, reminders, recurring tasks, and team collaboration. +## At a glance -Vikunja is ideal for individuals or teams who want full ownership of their productivity data while maintaining a modern and feature-rich task management experience. Pairing it with Tailscale ensures that your task system remains private while still being accessible from anywhere on your Tailnet. +| Item | Value | +| ------------- | ------------------------------------- | +| Web interface | `https://vikunja..ts.net` | +| Service port | `3456` | +| Image | `vikunja/vikunja` | +| Data | `./vikunja-data/files` (attachments) | +| | `./vikunja-data/db` (SQLite database) | -## Key Features +## Before you start -- Projects, tasks, and sub-tasks with flexible organization -- Labels, priorities, due dates, and reminders -- Recurring tasks and advanced filtering -- Collaboration and shared projects -- REST API and integrations -- Clean web UI and mobile app support +Set `VIKUNJA_SERVICE_PUBLICURL` in `.env` to the address of the web interface with a slash at the end, `https://vikunja..ts.net/`. -## Configuration Overview +## Deviations from the standard setup -In this setup, the `tailscale-vikunja` service runs Tailscale, which manages secure networking for Vikunja. The `vikunja` service uses the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This ensures the application is only accessible through your Tailnet unless you explicitly expose ports. +- **Runs as `root`.** The `application` container runs as user and group `0` through the `user` setting, so that Vikunja can write to the data folders that Docker creates. +- **Database.** `VIKUNJA_DATABASE_PATH` in `.env` puts the SQLite database in the mounted `./vikunja-data/db` folder. -### Service-Specific Notes +## First run -- On first launch, you will need to create an admin account via the web UI -- Default URL will be your Tailscale IP or MagicDNS name -- Vikunja stores data in its configured database (SQLite by default unless changed) +Open the web interface and register the first account. -## Useful Links +## Configuration -- Vikunja Website: -- Documentation: -- GitHub: +### Configuration file + +This directory contains `config.yml`, a sample configuration file with all settings as comments. To use it, edit the file and uncomment the line that mounts it in the `volumes` block of `compose.yaml`. + +## Links + +- [Vikunja documentation](https://vikunja.io/docs) +- [Vikunja source code](https://github.com/go-vikunja/vikunja) diff --git a/services/wallos/README.md b/services/wallos/README.md index 36e421d8..85857de6 100644 --- a/services/wallos/README.md +++ b/services/wallos/README.md @@ -1,22 +1,31 @@ -# Wallos with Tailscale Sidecar Configuration +# Wallos -This Docker Compose configuration sets up [Wallos](https://github.com/ellite/Wallos) with Tailscale as a sidecar container, enabling secure, private access to your self-hosted subscription tracker over your Tailscale network. With this setup, Wallos is never exposed to the public internet—access is limited strictly to devices authenticated through your Tailscale Tailnet. +[Wallos](https://github.com/ellite/Wallos) tracks your subscriptions. It shows your recurring expenses, reminds you of payments, and helps you to manage your budget. -## Wallos +This stack runs Wallos with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -Wallos is a self-hosted subscription tracking application that helps you manage and visualize your recurring expenses. With a simple and clean interface, Wallos makes it easy to log, track, and analyze your digital subscriptions without relying on any third-party services. Ideal for individuals looking to take control of their finances in a private and minimal environment. +## At a glance -## Key Features +| Item | Value | +| ------------- | -------------------------------------- | +| Web interface | `https://wallos..ts.net` | +| Service port | `80` | +| Image | `bellamy/wallos` | +| Data | `./wallos-data/db` (database) | +| | `./wallos-data/logos` (uploaded logos) | -* **Track Subscriptions Easily** – Add services with cost, billing frequency, and renewal dates. -* **Clean, Responsive UI** – Simple and modern interface that works on both desktop and mobile. -* **Visual Budgeting Tools** – View monthly and yearly overviews of your subscription spending. -* **Self-Hosted and Private** – Your data is stored and managed locally. -* **Lightweight Deployment** – Built to run efficiently in Docker with minimal configuration. -* **Private by Default with Tailscale** – Access your Wallos dashboard only from your Tailnet devices. +## Before you start -## Configuration Overview +Nothing beyond the [Quick Start](../../README.md#quick-start). -In this configuration, the `tailscale-wallos` container runs the Tailscale client and joins your private mesh network. The `wallos` container is set to use `network_mode: service:tailscale`, meaning all of Wallos’s network traffic is routed through the Tailscale container. This ensures that the Wallos interface is not publicly exposed and is only reachable from devices connected to your Tailscale network. +## Deviations from the standard setup -This approach combines self-hosted financial tracking with robust, zero-config VPN security—allowing you to safely manage your subscriptions from anywhere. +None. + +## First run + +Open the web interface. Wallos sends you to the registration page, where you create the first account, which becomes the administrator. + +## Links + +- [Wallos documentation and source code](https://github.com/ellite/Wallos) diff --git a/services/xwiki/README.md b/services/xwiki/README.md index 83a633bf..b9112e18 100644 --- a/services/xwiki/README.md +++ b/services/xwiki/README.md @@ -1,21 +1,35 @@ -# XWiki with Tailscale Sidecar Configuration +# XWiki -This Docker Compose configuration sets up **XWiki** with a Tailscale sidecar container, enabling secure, private access to your self-hosted wiki over your Tailnet. With this setup, your XWiki instance is **not exposed to the public internet** and is only accessible from authorized devices connected via Tailscale. +[XWiki](https://www.xwiki.org) is a wiki platform for documentation and knowledge management. It has structured pages, rights management, and many extensions. -## XWiki +This stack runs XWiki with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[**XWiki**](https://www.xwiki.org) is a powerful open-source wiki platform designed for collaboration, knowledge management, and building custom web applications. It combines the flexibility of a wiki with the structure of a CMS, making it suitable for teams, documentation hubs, and internal tools. +## At a glance -## Key Features +| Item | Value | +| ------------- | ----------------------------------------- | +| Web interface | `https://xwiki..ts.net` | +| Service port | `8080` | +| Images | `xwiki:stable-mariadb-tomcat` | +| | `mariadb:12` | +| Data | `./xwiki-data/xwiki` (XWiki data) | +| | `./xwiki-data/mariadb` (MariaDB database) | -- 📝 Rich content editing with WYSIWYG and Markdown support -- 👥 Advanced user permissions and access control -- 🔌 Highly extensible with plugins and macros -- 📊 Structured data and application-building capabilities -- 🔍 Full-text search and content organization tools -- 🏢 Ideal for internal documentation and knowledge bases +## Before you start -## Resources +Change `DB_PASSWORD` and `MARIADB_ROOT_PASSWORD` in `.env` before the first start. The default for both is `xwiki`. -- XWiki Docker Repo: -- XWiki Documentation: +## Deviations from the standard setup + +- **Extra container.** The stack runs a `db` container with MariaDB, named `db-xwiki`. It uses the default Compose network, and XWiki reaches it by its container name through Docker's DNS. Keep `TS_ACCEPT_DNS` disabled, because MagicDNS cannot resolve that name. +- **Database setup.** This directory contains `init.sql`, which the database container runs when it first creates the database. +- **Service port.** XWiki listens on port `8080`. `SERVICEPORT` in `.env` is only used by the optional `ports` block. + +## First run + +Open the web interface. The first start takes a few minutes. XWiki then shows its distribution wizard, where you create the administrator account and install the standard flavor. + +## Links + +- [XWiki documentation](https://www.xwiki.org/xwiki/bin/view/Documentation/) +- [XWiki Docker image](https://github.com/xwiki/xwiki-docker) diff --git a/templates/service-template/README.md b/templates/service-template/README.md index 7ceac722..1ef10691 100644 --- a/templates/service-template/README.md +++ b/templates/service-template/README.md @@ -1,26 +1,31 @@ -# SERVICE with Tailscale Sidecar Configuration +# SERVICE -This Docker Compose configuration sets up [SERVICE](LINK TO PAGE OF MAINTAINER) with Tailscale as a sidecar container to keep the app reachable over your Tailnet. +[SERVICE](LINK TO THE UPSTREAM PROJECT) EXPLAIN WHAT THE SERVICE DOES IN ONE OR TWO SENTENCES. -## SERVICE +This stack runs SERVICE with a Tailscale sidecar, as described in [the standard setup](../../documentation/standard-setup.md). -[SERVICE](LINK TO PAGE OF MAINTAINER) information about the service. Explain what the app does in 2-3 sentences and why someone would pair it with Tailscale. +## At a glance -## Configuration Overview +| Item | Value | +| ------------- | ---------------------------------- | +| Web interface | `https://SERVICE..ts.net` | +| Service port | `80` | +| Image | `IMAGE` | +| Data | `./SERVICE-data/` | -In this setup, the `tailscale` service (container `tailscale-SERVICE`) runs Tailscale, which manages secure networking for SERVICE. The `application` service (container `app-SERVICE`) uses the Tailscale network stack via Docker's `network_mode: service:tailscale` configuration. This keeps the app Tailnet-only unless you intentionally expose ports. +## Before you start -## What to document for users +Nothing beyond the [Quick Start](../../README.md#quick-start). -- Prerequisites: note if the host user needs `docker` group membership, GPU/video/render groups, or any devices passed through. -- Volumes: list bind mounts that should be pre-created so Docker does not create root-owned directories; rename any conflicting config folders (for example, `ts-config`) if needed. -- MagicDNS/Serve: when to enable `TS_ACCEPT_DNS`, what to set for `TS_CERT_DOMAIN`, and which port should be in `serve.json` (it does not consume `.env` values automatically). -- Ports: explain whether the commented `0.0.0.0:${SERVICEPORT}:${SERVICEPORT}` mapping is necessary for this app or should stay removed for Tailnet-only access. -- Service-specific gotchas: initial admin setup, default credentials, path expectations, or other quirks to check before first launch. -- Links: include upstream docs for the service and any official setup guides or videos that help users understand the app. +## Deviations from the standard setup -## Files to check +None. -Please check the following contents for validity as some variables need to be defined upfront. +## First run -- `.env` // Main variable `TS_AUTHKEY` +DESCRIBE WHAT THE USER DOES AFTER THE FIRST START, SUCH AS CREATING THE FIRST ACCOUNT. + +## Links + +- [SERVICE documentation](LINK TO THE UPSTREAM DOCUMENTATION) +- [SERVICE source code](LINK TO THE UPSTREAM REPOSITORY) From da83a7f59ad404e8cdfa56e9ce5016567e79c6fd Mon Sep 17 00:00:00 2001 From: Jack Spiering <46534141+jackspiering@users.noreply.github.com> Date: Wed, 7 Oct 2026 20:26:43 +0200 Subject: [PATCH 2/2] Nessus: say that the image does not support storage volumes --- services/nessus/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/services/nessus/README.md b/services/nessus/README.md index 0ec6741e..15d79753 100644 --- a/services/nessus/README.md +++ b/services/nessus/README.md @@ -21,7 +21,7 @@ Request an activation code, for example for [Nessus Essentials](https://www.tena ## Deviations from the standard setup -- **No data folder.** The stack has no volumes for Nessus. Your settings, scans, and license activation are lost when the container is recreated, for example after an image update. +- **No data folder.** Tenable does not support storage volumes for the Nessus image, so the stack has none. Your settings, scans, and license activation are lost when the container is recreated, for example after an image update. The Tenable documentation lists environment variables, such as `USERNAME`, `PASSWORD`, and `ACTIVATION_CODE`, that set up Nessus again at each start. - **Serve forwards to HTTPS.** Nessus serves its web interface on port `8834` with a self-signed certificate. Tailscale Serve forwards to it with `https+insecure`. ## First run