# Production Deployment

This deployment is independent from all other projects. It uses:

- A dedicated Linux user, `rkt`
- An application checkout at `/opt/roaring-kitty-tracker`
- `roaring-kitty-tracker.service` for the dashboard and API
- `roaring-kitty-refresh.timer` for weekday data and score refreshes
- Caddy as the public HTTPS reverse proxy
- Cloudflare only for DNS and proxying, so the dashboard and API stay on one origin

There are two options:

- `install-hetzner.sh` runs a systemd-native deployment on a dedicated server.
- `install-hetzner-docker.sh` is for the existing `lorespace-demo-1` Hetzner host. It runs in its own Docker Compose project and data volumes, and adds only one Caddy hostname route to the existing shared edge proxy.

## Hetzner setup

1. Create a new Hetzner server, or a dedicated VM, with Ubuntu 24.04 or Debian 12.
2. Point a Cloudflare DNS `A` record such as `tracker.example.com` to the server IPv4 address and enable the orange-cloud proxy.
3. In Cloudflare, set SSL/TLS encryption mode to **Full (strict)**.
4. Open inbound TCP ports `80`, `443`, and `22` in the Hetzner firewall. Do not expose port `8765`.
5. Copy this repository onto the server. If the repository is private, configure a read-only Git deploy key first.
6. From the repository root, run:

   ```bash
   sudo RKT_DOMAIN=tracker.example.com bash deploy/install-hetzner.sh
   ```

7. Verify the public health endpoint:

   ```bash
   curl -fsS https://tracker.example.com/healthz
   ```

## Operations

```bash
sudo systemctl status roaring-kitty-tracker
sudo systemctl status roaring-kitty-refresh.timer
sudo journalctl -u roaring-kitty-refresh.service -f
sudo systemctl start roaring-kitty-refresh.service
sudo systemctl restart roaring-kitty-tracker
```

The refresh job respects the downloader cache windows. To force every source download, run manually as the application user:

```bash
sudo -u rkt bash /opt/roaring-kitty-tracker/run_all.sh --force-data
```

The dashboard reads output files for every request, so a completed refresh is visible without restarting the public service.

## Existing Hetzner host

The Docker deployment uses the existing Caddy Docker network only as a reverse-proxy boundary. It does not join the LoreSpace Compose project, reuse its containers, or share application data.

1. Clone this repository at `/opt/roaring-kitty-tracker`.
2. Select a Cloudflare-managed hostname and create a proxied DNS `A` record to the Hetzner IPv4 address.
3. Run the installer from the clone:

   ```bash
   cd /opt/roaring-kitty-tracker
   RKT_DOMAIN=tracker.example.com bash deploy/install-hetzner-docker.sh
   ```

4. Trigger the initial full data run and follow its logs:

   ```bash
   sudo systemctl start roaring-kitty-refresh-docker.service
   sudo journalctl -u roaring-kitty-refresh-docker.service -f
   ```

## Existing Hetzner Host Without Sudo

`install-hetzner-user.sh` is for a Docker-enabled deployment account that owns
the shared Caddyfile but does not have passwordless sudo. It keeps the tracker
in that account's home directory, uses its own Compose volumes, and installs a
weekday refresh in that account's crontab. It does not alter system services or
the LoreSpace Compose project.

The companion `deploy/cloudflare-pages/` package publishes the frontend to a
free `*.pages.dev` address. Its Pages middleware proxies dashboard API requests
to the tracker hostname, so the browser continues using same-origin `/api/*`
requests and does not need CORS configuration.