From 1c7da2bef5d2c5a441603b7d1160c5b6a226e1e9 Mon Sep 17 00:00:00 2001 From: peskyadmin Date: Sun, 2 Aug 2026 16:26:58 -0400 Subject: [PATCH] docs: rewrite README with clear Tailscale vs Headscale paths - Tailscale as default (Quick Start at top) - Headscale section at bottom with explicit steps - Clear .env changes for each environment - Updated serve config switching table --- README.md | 179 +++++++++++++----------------------------------------- 1 file changed, 43 insertions(+), 136 deletions(-) diff --git a/README.md b/README.md index 7ec1d5d..a8e1da2 100644 --- a/README.md +++ b/README.md @@ -2,158 +2,65 @@ ![Vikunja with Tailscale](https://raw.githubusercontent.com/go-vikunja/vikunja/main/frontend/src/assets/logo.svg "Vikunja") -This project sets up a Vikunja instance with Tailscale VPN integration using Docker Compose. It creates a secure, private network connection for your Vikunja instance using Tailscale. +This project sets up a Vikunja 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-vikunja/ -├── docker-compose.yml -├── tailscale/ -│ ├── tailscale-data/ # Persistent Tailscale state -│ └── config/ # Tailscale configuration files -└── vikunja/ - └── config/ # Vikunja configuration files -``` - -## Setup Instructions - -1. **Clone the Repository** +1. Copy the example environment file and fill in your values: ```bash - git clone https://gitea.example.com/org/ts-vikunja - cd ts-vikunja + 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 + - `TS_LOGIN_SERVER` — leave as `https://controlplane.tailscale.com` (default) +3. Start the stack: + ```bash + docker compose up -d + ``` +4. Access Vikunja at `http://vikunja..ts.net` -4. Configure Vikunja - - 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] - -7. Login - - After starting the services your service should be available via tailnet at https://vikunja.{{YOUR_TAILNET_DOMAIN}}.ts.net ie https://vikunja.tail12345.ts.net/ - -## Services - -### vikunja-ts (Tailscale) - -- Runs Tailscale VPN client -- Image: tailscale/tailscale:latest -- Container name: vikunja-ts -- Hostname: vikunja -- Requires NET_ADMIN and SYS_MODULE capabilities -- Persists state in ./tailscale/tailscale-data -- Uses configuration from ./tailscale/config - -### vikunja - -- Depends on vikunja-ts service - -## Usage - -- After starting the services your service should be available via tailnet at `https://vikunja.{{YOUR_TAILNET_DOMAIN}}.ts.net` ie `https://vikunja.tail12345.ts.net/` -- To manually get the Tailscale IP/hostname of your container: - ```bash - docker logs vikunja-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: - - 3456:3456 - ``` -- Stopping the Services - ```bash - docker compose down - ``` - -## Troubleshooting -- Check container logs: - ```bash - docker logs vikunja-ts - docker logs vikunja - ``` -- 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 Vikunja service uses the Tailscale service's network stack via `network_mode: service:vikunja-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/ - - Vikunja [documentation]({{service_docs}}) - - Vikunja [repository]({{service_repo}}) - - Vikunja [linuxserve.io]({{service_lcsr}}) -## Tailscale Serve Configuration - -This repo includes two serve configuration files: - -- `tailscale/config/serve.json` — Default (recommended for Tailscale with MagicDNS + certs) -- `tailscale/config/serve.headscale.json` — For Headscale or Tailscale without certs (HTTP only) - -### How to use - -**Tailscale (default):** -- No changes needed. The default `serve.json` will be used. - -**Headscale:** -1. Copy `serve.headscale.json` over `serve.json`: +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 ``` -2. Update the hostname in `serve.json` to match your service. - -After changing the serve config, restart the sidecar: -```bash -docker compose restart -ts -``` +4. Edit `serve.json` and replace `vikunja.example.com` with your actual domain +5. Start the stack: + ```bash + docker compose up -d + ``` +6. Access Vikunja at `http://vikunja.yourdomain.com` ## Configuration -### Environment Variables +See `.env.example` for all available options. -Copy `.env.example` to `.env` and fill in your values: +### Switching Serve Configs +| Environment | File to use | Notes | +|-------------------|--------------------------------------|-------| +| Tailscale (default) | `tailscale/config/serve.json` | Supports HTTP + HTTPS with certs | +| Headscale | `tailscale/config/serve.headscale.json` | HTTP only | + +After changing the serve config, restart the sidecar: ```bash -cp .env.example .env -``` - -### Tailscale Serve Configuration - -This repo ships with two serve configuration options: - -| File | Use Case | Description | -|------|----------|-------------| -| `tailscale/config/serve.json` | Tailscale (default) | Supports both HTTP and HTTPS when MagicDNS + certs are configured | -| `tailscale/config/serve.headscale.json` | Headscale / no certs | HTTP-only on port 3456 | - -**To switch to Headscale mode:** - -```bash -cp tailscale/config/serve.headscale.json tailscale/config/serve.json docker compose restart vikunja-ts ``` -Update the hostname in `serve.headscale.json` to match your service. +## Optional: Direct Host Access + +Uncomment the ports section in `docker-compose.yml` if you need direct access without Tailscale: +```yaml +ports: + - 3456:3456 +```