diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..f942de7 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,27 @@ +# Contributing to ScaleTail + +Thanks for helping expand these Tailscale sidecar examples. Keeping services aligned with the template makes it easier for users to migrate existing Compose stacks without breaking them. + +## Adding a new service + +1. Copy `templates/service-template` into `services/` and rename the compose and README files accordingly. +2. Update `compose.yaml`: + - Keep the Tailscale container named `tailscale-` and the app container named `app-`. + - Set `IMAGE_URL`, `SERVICEPORT`, and any other app variables in `.env`; do not commit secrets or real auth keys. + - Leave `network_mode: service:tailscale` in place and keep `depends_on` using the Tailscale health check. + - Keep the `ports` section commented unless LAN exposure is required; explain why in the README if you expose anything. + - Adjust volumes to match the service, and pre-create bind-mount paths so Docker does not create root-owned folders. (optional) + - If the service needs devices (GPU, render, fuse, etc.) or extra capabilities, add them explicitly and mention them in the README. (optional) +3. Update `"Proxy":"http://127.0.0.1:80"` in `compose.yaml` with the app's actual internal port; it does not consume `.env` values automatically. Remove `TS_SERVE_CONFIG` if Serve/Funnel is not needed. +4. Fill in the service README using the template: + - Briefly describe the app and why Tailscale helps. + - List prerequisites (user in `docker` group, GPU/group membership, devices). + - Call out gotchas: initial admin setup, default credentials, path expectations, required group IDs, or config directory names that must change. + - Clarify MagicDNS/HTTPS steps (`TS_ACCEPT_DNS`), optional 0.0.0.0 port exposure, and any health checks. + - Link to upstream service docs and any official setup videos. +5. Sanity-check the stack with `docker compose config` from the service directory to catch typos and missing variables. + +## Updating an existing service + +- Keep the sidecar pattern intact (`network_mode: service:tailscale`, health checks, `depends_on`). +- Avoid removing existing volumes or changing container names unless the change is clearly documented in the README. diff --git a/README.md b/README.md index 6cf9552..8e5436c 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,7 @@ If you would like to add your own config, you can use the [service-template](tem - [ScaleTail - Tailscale Docker Sidecar Configuration Examples](#scaletail---tailscale-docker-sidecar-configuration-examples) - [Table of Contents](#table-of-contents) + - [Helpful videos and docs](#helpful-videos-and-docs) - [Available Configurations](#available-configurations) - [🌐 Networking and Security](#-networking-and-security) - [🎥 Media and Entertainment](#-media-and-entertainment) @@ -25,16 +26,22 @@ If you would like to add your own config, you can use the [service-template](tem - [Tailscale Funnel](#tailscale-funnel) - [Tailscale Serve](#tailscale-serve) - [Tailscale Documentation](#tailscale-documentation) + - [Contributing](#contributing) - [Star History](#star-history) - [License](#license) +### Helpful videos and docs + +- Tailscale Docker sidecar guide and Serve/Funnel walkthroughs on the official [Tailscale YouTube channel](https://www.youtube.com/@Tailscale) pair well with these examples. +- The Tailscale [Docker guide](https://tailscale.com/blog/docker-tailscale-guide), [Serve docs](https://tailscale.com/kb/1242/tailscale-serve), and [Funnel docs](https://tailscale.com/kb/1223/funnel) cover the underlying features without duplicating content here. + ## Available Configurations ### 🌐 Networking and Security | 🌐 Service | 📝 Description | 🔗 Link | | ------------------------- | ------------------------------------------------------------------------------- | --------------------------------------- | -| 🛡️ **AdGuard Home** | Network-wide software for blocking ads and tracking. | [Details](services/adguardhome) | +| 🛡️ **AdGuard Home** | Network-wide software for blocking ads and tracking. | [Details](services/adguardhome) | | 🔄 **AdGuardHome Sync** | A tool for syncing configuration across multiple AdGuard Home instances. | [Details](services/adguardhome-sync) | | 🌐 **Caddy** | Caddy is an extensible server platform that uses TLS by default. | [Details](services/caddy) | | 🌐 **DDNS Updater** | A self-hosted solution to keep DNS A/AAAA records updated automatically. | [Details](services/ddns-updater) | @@ -70,7 +77,6 @@ If you would like to add your own config, you can use the [service-template](tem | 🖼️ **Posterizarr** | Automatically generates and updates posters/artwork for media libraries. | [Details](services/posterizarr) | | ♻️ **Recyclarr** | Tools for managing, migrating, and maintaining indexers and quality profiles. | [Details](services/recyclarr) | - ### 💼 Productivity and Collaboration | 💼 Service | 📝 Description | 🔗 Link | @@ -191,6 +197,10 @@ An example configuration for Tailscale Serve for your service is [available here - [Tailscale.com - Docker Tailscale Guide](https://tailscale.com/blog/docker-tailscale-guide) - [Tailscale - for ARM / OpenPli Setupbox](documentation/tailscale-on-arm.md) +## Contributing + +See `CONTRIBUTING.md` for guidance on adding services with the template, documenting gotchas, and keeping Tailscale-sidecar setups consistent. + ## Star History [![Star History Chart](https://api.star-history.com/svg?repos=2tiny2scale/scaletail&type=Date)](https://www.star-history.com/#2tiny2scale/scaletail&Date) diff --git a/templates/service-template/README.md b/templates/service-template/README.md index ee32ec9..58af12c 100644 --- a/templates/service-template/README.md +++ b/templates/service-template/README.md @@ -1,20 +1,26 @@ -# Make sure you replace SERVICE. - # SERVICE with Tailscale Sidecar Configuration -This Docker Compose configuration sets up [SERVICE](LINK TO PAGE OF MAINTAINER) with Tailscale as a sidecar container ...... +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 -[SERVICE](LINK TO PAGE OF MAINTAINER) information about service... +[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. ## Configuration Overview -In this setup, the `tailscale-SERVICE` service runs Tailscale, which manages secure networking for the SERVICE. The `SERVICE` service utilizes the Tailscale network stack via Docker's `network_mode: service:` configuration. This setup ensures that SERVICE's service is only accessible through the Tailscale network (or locally, if preferred), providing an extra layer of security and privacy for your SERVICE. +In this setup, the `tailscale-SERVICE` service runs Tailscale, which manages secure networking for SERVICE. The `SERVICE` service utilizes the Tailscale network stack via Docker's `network_mode: service:` configuration. This keeps the app Tailnet-only unless you intentionally expose ports. + +## What to document for users + +- 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. ## Files to check Please check the following contents for validity as some variables need to be defined upfront. -- `.env` // This files hold the main parts -- `./config/serve.json` // This file requires a service port of the app to be defined +- `.env` // Main variable `TS_AUTHKEY`