From 38f5f9252dd114cfb35b98d66985882ae293333d Mon Sep 17 00:00:00 2001 From: Jack Spiering <46534141+jackspiering@users.noreply.github.com> Date: Thu, 10 Sep 2026 18:36:52 +0200 Subject: [PATCH 1/2] Add agent and contributor guidance --- AGENTS.md | 26 ++++++++++++ CONTRIBUTING.md | 107 +++++++++++++++++++++++++++++++++++++----------- 2 files changed, 108 insertions(+), 25 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..1d1221d4 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,26 @@ +# Agent guidance + +Follow [CONTRIBUTING.md](CONTRIBUTING.md) and the current service template. + +## Before you edit + +- Inspect the target service and its README. +- Confirm ports, commands, volumes, and variables in the image's upstream docs. +- Preserve service-specific exceptions that still apply. +- Keep changes focused on the requested service or documentation. +- Never commit working auth keys, passwords, tokens, or other credentials. + +## Verification + +Run `docker compose config --quiet` from each changed service directory. When +possible, start the stack and test its main function through the Tailnet. + +Run these checks for changed Markdown files: + +```sh +rumdl check --config .markdownlint.yml +git diff --check +``` + +Report the checks you ran. State any checks that credentials, hardware, +permissions, or unavailable tools prevented. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f942de7c..a94e5d3c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,27 +1,84 @@ # 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. +Thanks for helping improve these Tailscale sidecar examples. + +## Add a service + +1. Copy the service template from the repository root: + + ```sh + cp -R templates/service-template services/ + ``` + + This command includes the hidden `.env` file. Use a lowercase directory name. + +2. Update `.env` with safe example values. + + Set `SERVICE`, `IMAGE_URL`, `SERVICEPORT`, and the application variables. + Never commit a working auth key, password, token, or other credential. + +3. Adapt `compose.yaml`. + + - Keep the Compose service keys `tailscale` and `application`. + - Name the containers `tailscale-${SERVICE}` and `app-${SERVICE}`. + - Keep `network_mode: service:tailscale` on the application. + - Keep the application's health-based dependency on `tailscale`. + - Add all required persistent volumes. + - Add required devices and capabilities explicitly. + +4. Set the Serve proxy to the application's internal port. + + The Serve JSON does not read `SERVICEPORT` from `.env`. Keep runtime variables + escaped, such as `$${TS_CERT_DOMAIN}`. + + Keep the `ports` block commented for Tailnet-only access. Document any LAN + port you expose. Remove the Serve configuration when the service does not use + Tailscale Serve. + +5. Add a health check that the application image can run. + + Prefer an application endpoint or an upstream health command. Remove the + application health check when no reliable check exists. Keep the Tailscale + health check. + +6. Complete the service README. + + Document prerequisites, persistent paths, setup steps, ports, Tailnet access, + and service-specific exceptions. Link to the upstream documentation. + +7. Add the service to the correct category in the root `README.md`. + + Keep the entries in that category alphabetized. + +## Update a service + +- Read the service README and Compose file before you make changes. +- Preserve the shared network namespace and Tailscale dependency. +- Preserve persistent volumes unless you document a safe migration. +- Use `${VARIABLE}` for Compose interpolation, not `$(VARIABLE)`. +- Update the service README when ports, paths, setup, or behavior change. +- Update the root service list when you add, remove, or rename a service. + +Preserve valid service-specific exceptions. + +## Verify your change + +Run Compose validation from each changed service directory: + +```sh +docker compose config --quiet +``` + +This command does not prove that the application works. + +When possible, start the stack and confirm: + +- Tailscale becomes healthy and joins the Tailnet. +- The application starts and is reachable through the Tailnet. +- The application's main function works. +- Persistent storage and documented LAN access work, when applicable. + +## Submit a pull request + +Follow the pull request template. Report the checks you ran and any checks you +could not run. From 28e11529bae62a1b35763b7274e249878c35b8a4 Mon Sep 17 00:00:00 2001 From: Jack Spiering <46534141+jackspiering@users.noreply.github.com> Date: Thu, 10 Sep 2026 18:59:05 +0200 Subject: [PATCH 2/2] Make documentation command examples executable --- AGENTS.md | 4 ++-- CONTRIBUTING.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 1d1221d4..97bf57b4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -15,10 +15,10 @@ Follow [CONTRIBUTING.md](CONTRIBUTING.md) and the current service template. Run `docker compose config --quiet` from each changed service directory. When possible, start the stack and test its main function through the Tailnet. -Run these checks for changed Markdown files: +From the repository root, lint the changed Markdown files. Replace the example paths below as needed: ```sh -rumdl check --config .markdownlint.yml +rumdl check --config .markdownlint.yml AGENTS.md CONTRIBUTING.md git diff --check ``` diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a94e5d3c..1c8e487a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,10 +4,10 @@ Thanks for helping improve these Tailscale sidecar examples. ## Add a service -1. Copy the service template from the repository root: +1. Copy the service template from the repository root. Replace `my-service` with your service name: ```sh - cp -R templates/service-template services/ + cp -R templates/service-template services/my-service ``` This command includes the hidden `.env` file. Use a lowercase directory name.