feat: improve template structure and documentation

- Add dual serve config (serve.json + serve.headscale.json) - Add SECURITY.md with default passwords warning - Add .env.example with clear REQUIRED / REFERENCE / CUSTOMIZE sections - Rewrite README with clear Tailscale vs Headscale paths - Harden .gitignore (env files, keys, Tailscale state) - Update docker-compose.yml with clear section labels - Make volume names service-specific ({{service}}-db-data) - Ensure both db and app services depend on the Tailscale sidecar
2026-08-02 19:03:59 -04:00
parent e727d07025
commit e71e6f8bf5
7 changed files with 187 additions and 108 deletions
--- a/README.md
+++ b/README.md
@@ -1,108 +1,70 @@
 # {{Service}} with Tailscale Integration

-![{{Service}} with Tailscale](https://damconsulting.llc/images/logo_yellow.svg "{{Service}}")
+![{{Service}} with Tailscale](https://raw.githubusercontent.com/go-vikunja/vikunja/main/frontend/src/assets/logo.svg "{{Service}}")

-This project sets up a {{Service}} instance with Tailscale VPN integration using Docker Compose. It creates a secure, private network connection for your {{Service}} instance using Tailscale.
+This project sets up a {{Service}} instance with Tailscale VPN integration using Docker Compose.

-## Prerequisites
+## Quick Start (Tailscale)

- Docker and Docker Compose installed on your system
- A Tailscale account and auth key (get one from https://login.tailscale.com/admin/authkeys)
- Basic understanding of Docker and networking concepts
-
-## Project Structure
-```
-ts-{{service}}/
-├── docker-compose.yml
-├── tailscale/
-│   ├── tailscale-data/     # Persistent Tailscale state
-│   └── config/             # Tailscale configuration files
-└── {{service}}/
-    └── config/             # {{Service}} configuration files
-```
-
-## Setup Instructions
-
-1. **Clone the Repository**
+1. Copy the example environment file and fill in your values:
   ```bash
-   git clone https://gitea.damconsulting.llc/DAM/ts-{{service}}
-   cd ts-{{service}}
+   cp .env.example .env
   ```
-2. Create Required Directories
-    ```bash
-    mkdir -p tailscale/tailscale-data
-    ```
-3. Configure Tailscale
-    - Make sure `TS_AUTHKEY` and `TS_LOGIN_SERVER` are set in your environment (or a local `.env` file) before running docker compose.
-    - Optionally, update the file in `tailscale/config/serve.json` if you need specific Tailscale serve configurations
-        - CAUTION: Changing `"${TS_CERT_DOMAIN}:443": false` to `true` will expose the service to the internet
+2. Edit `.env` and set:
+   - `TS_AUTHKEY` — your Tailscale auth key
+3. Start the stack:
+   ```bash
+   docker compose up -d
+   ```
+4. Customize the app config per official documentation
+5. Access {{Service}} at `http://{{service}}.<your-tailnet>.ts.net`

-4. Configure {{Service}}
-    - See the [documentation]({{service_docs}}) for configuration options
+## Headscale

-5. Start the Services
-    ```bash
-    docker compose up -d
-    ```
+If you're using Headscale instead of Tailscale:

-6. Wait for Certificate to propagate [~2m] 
+1. Copy the example environment file:
+   ```bash
+   cp .env.example .env
+   ```
+2. Edit `.env` and set:
+   - `TS_AUTHKEY` — your Headscale auth key
+   - `TS_LOGIN_SERVER` — your Headscale server URL
+3. Switch to the Headscale serve config:
+   ```bash
+   cp tailscale/config/serve.headscale.json tailscale/config/serve.json
+   ```
+4. Edit `serve.json` and replace `{{service}}.example.com` with your actual domain
+5. Start the stack:
+   ```bash
+   docker compose up -d
+   ```
+6. Customs the app config per official documentation
+7. Access {{Service}} at `http://{{service}}.yourdomain.com`

-7. Login 
-    - After starting the services your service should be available via tailnet at https://{{service}}.{{YOUR_TAILNET_DOMAIN}}.ts.net ie https://{{service}}.tail12345.ts.net/
+## Configuration

-## Services
+See `.env.example` for all available options.

-### {{service}}-ts (Tailscale)
+### Switching Serve Configs

- Runs Tailscale VPN client
- Image: tailscale/tailscale:latest
- Container name: {{service}}-ts
- Hostname: {{service}}
- Requires NET_ADMIN and SYS_MODULE capabilities
- Persists state in ./tailscale/tailscale-data
- Uses configuration from ./tailscale/config
+| Environment       | File to use                          | Notes |
+|-------------------|--------------------------------------|-------|
+| Tailscale (default) | `tailscale/config/serve.json`       | Supports HTTP + HTTPS with certs |
+| Headscale         | `tailscale/config/serve.headscale.json` | HTTP only |

-### {{service}}
+After changing the serve config, restart the sidecar:
+```bash
+docker compose restart {{service}}-ts
+```

- Depends on {{service}}-ts service
+## Optional: Direct Host Access

-## Usage
+Uncomment the ports section in `docker-compose.yml` if you need direct access without Tailscale:
+```yaml
+ports:
+  - {{port}}:{{port}}
+```

- After starting the services your service should be available via tailnet at `https://{{service}}.{{YOUR_TAILNET_DOMAIN}}.ts.net` ie `https://{{service}}.tail12345.ts.net/`
- To manually get the Tailscale IP/hostname of your container:
-    ```bash
-    docker logs {{service}}-ts
-    ```
-    Look for the Tailscale IP address in the logs.
-
-## Optional Features
-
- Uncomment and adjust the ports mapping if you need direct access (without Tailscale):
-    ```yaml
-    ports:
-    - 3000:3000
-    ```
- Stopping the Services
-    ```bash
-    docker compose down
-    ```
-
-## Troubleshooting
- Check container logs:
-    ```bash
-    docker logs {{service}}-ts
-    docker logs {{service}}
-    ```
- Ensure your Tailscale auth key is valid and not expired
- Verify the configuration files have proper permissions
- Make sure required directories exist before starting
-
-## Notes
- The {{Service}} service uses the Tailscale service's network stack via `network_mode: service:{{service}}-ts`
- Direct port mapping is disabled by default as Tailscale handles the networking
- Services restart automatically unless explicitly stopped
- For more information:
-    - Tailscale documentation: https://tailscale.com/kb/
-    - {{Service}} [documentation]({{service_docs}})
-    - {{Service}} [repository]({{service_repo}})
-    - {{Service}} [linuxserve.io]({{service_lcsr}})
+## Links
+put links to offical site, and git repo