Tracearr

https://docs.tracearr.com
Admin
Tracearr is a free, open-source real-time monitoring platform for Plex, Jellyfin, and Emby that...
Tokens:11,480
Snippets:197
Trust Score:4.9
Update:5 months ago
Show doc for...
Tokens:
Raw
### Download and Start Supervised Tracearr

Source: https://docs.tracearr.com/getting-started/installation/supervised

Download the example compose file and start Tracearr in detached mode. No .env file is needed as secrets are auto-generated.

```bash
curl -O https://raw.githubusercontent.com/connorgallopo/Tracearr/main/docker/examples/docker-compose.supervised-example.yml
 
docker compose -f docker-compose.supervised-example.yml up -d
```

--------------------------------

### Quick Start: Install Tracearr with Docker Compose (Linux/macOS)

Source: https://docs.tracearr.com/getting-started/installation

Download the compose file, generate secrets, and start Tracearr using Docker Compose on Linux or macOS.

```bash
curl -O https://raw.githubusercontent.com/connorgallopo/Tracearr/main/docker/examples/docker-compose.pg18.yml

echo "JWT_SECRET=$(openssl rand -hex 32)" > .env
echo "COOKIE_SECRET=$(openssl rand -hex 32)" >> .env

docker compose -f docker-compose.pg18.yml up -d
```

--------------------------------

### Install Tracearr with Helm

Source: https://docs.tracearr.com/getting-started/installation/kubernetes

Clone the repository, navigate to the Helm directory, and install the chart into a dedicated namespace. Init containers will automatically handle waiting for database dependencies.

```bash
git clone https://github.com/connorgallopo/Tracearr.git
cd Tracearr/docker/helm

helm install tracearr ./tracearr --namespace tracearr --create-namespace
```

--------------------------------

### Quick Start: Install Tracearr with Docker Compose (Windows PowerShell)

Source: https://docs.tracearr.com/getting-started/installation

Download the compose file, generate secrets, and start Tracearr using Docker Compose on Windows PowerShell.

```powershell
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/connorgallopo/Tracearr/main/docker/examples/docker-compose.pg18.yml" -OutFile "docker-compose.pg18.yml"

"JWT_SECRET=$(-join (1..16 | %{'{0:x2}' -f (Get-Random -Max 256)}))" | Out-File -Encoding ascii .env
"COOKIE_SECRET=$(-join (1..16 | %{'{0:x2}' -f (Get-Random -Max 256)}))" | Out-File -Encoding ascii -Append .env

docker compose -f docker-compose.pg18.yml up -d
```

--------------------------------

### Recreate Docker Compose Stack

Source: https://docs.tracearr.com/faq

After modifying your Docker Compose file to disable IPv6, use these commands to stop the existing stack and start a new one with the updated configuration.

```bash
docker compose -f your-compose-file.yml down
docker compose -f your-compose-file.yml up -d
```

--------------------------------

### Create Backup via CLI

Source: https://docs.tracearr.com/getting-started/installation

Use this command to initiate a database backup through the Tracearr command-line interface. This ensures a consistent snapshot.

```bash
# Create a backup via CLI
docker exec tracearr node apps/server/scripts/backup.ts
```

--------------------------------

### Create Database Backup via CLI

Source: https://docs.tracearr.com/getting-started/installation/supervised

Execute a command within the running Tracearr container to create a database backup.

```bash
docker exec tracearr node apps/server/scripts/backup.ts
```

--------------------------------

### Viewing Standard Docker Logs

Source: https://docs.tracearr.com/configuration/debug

Retrieve logs for the application, database, and cache containers using standard Docker log commands.

```bash
docker logs tracearr          # Application logs
```

```bash
docker logs tracearr-db       # Database logs
```

```bash
docker logs tracearr-redis    # Cache logs
```

--------------------------------

### Create Backup via CLI (JSON Output)

Source: https://docs.tracearr.com/configuration/backup

Execute the Tracearr CLI backup script with the --json flag for machine-readable output, suitable for cron jobs or wrapper scripts.

```bash
docker exec tracearr node apps/server/scripts/backup.ts --json
```

--------------------------------

### Set PostgreSQL/TimescaleDB Connection String

Source: https://docs.tracearr.com/configuration/environment

Configure the DATABASE_URL to connect Tracearr to your PostgreSQL or TimescaleDB instance. Ensure the connection string includes user, password, host, port, and database name.

```bash
DATABASE_URL=postgres://tracearr:password@localhost:5432/tracearr
```

--------------------------------

### Set Redis Connection String with Authentication

Source: https://docs.tracearr.com/configuration/environment

When your Redis instance requires authentication, include the password in the REDIS_URL. Ensure the format is redis://:password@host:port.

```bash
REDIS_URL=redis://:password@localhost:6379
```

--------------------------------

### Enable Gzip Compression

Source: https://docs.tracearr.com/configuration/environment

Set GZIP_ENABLED=true to enable server-side gzip compression for HTTP responses. This reduces bandwidth usage but may increase CPU load. Only enable if Tracearr is serving traffic directly without a compressing proxy.

```bash
GZIP_ENABLED=true
```

--------------------------------

### Set Custom Backup Directory

Source: https://docs.tracearr.com/configuration/environment

Configure BACKUP_DIR to specify a custom location for storing database backups. Ensure the directory is writable and mounted as a volume if necessary, especially when using Docker.

```bash
BACKUP_DIR=/custom/path/to/backups
```

--------------------------------

### Monitor and Access Tracearr Pods

Source: https://docs.tracearr.com/getting-started/installation/kubernetes

Watch the pods as they come online in the specified namespace. Use port-forwarding to access the Tracearr UI locally.

```bash
kubectl get pods -n tracearr -w
```

```bash
kubectl port-forward svc/tracearr 3000:3000 -n tracearr
```

--------------------------------

### Viewing Proxmox VE LXC Logs with systemd

Source: https://docs.tracearr.com/configuration/debug

Access application, database, and cache logs within a Proxmox VE LXC environment using systemd journal commands.

```bash
journalctl -u tracearr   # Application logs
```

```bash
journalctl -u postgresql # Database logs
```

```bash
journalctl -u redis      # Cache logs
```

--------------------------------

### Mount Backup Directory with Docker Compose

Source: https://docs.tracearr.com/configuration/backup

Persist backups on the host by mounting the default backup path as a bind mount in your Docker Compose file. This ensures backups are accessible outside the container.

```yaml
volumes:
  - /path/to/backups:/data/backup
```

--------------------------------

### Configure External Database

Source: https://docs.tracearr.com/getting-started/installation/kubernetes

Skip the bundled TimescaleDB StatefulSet and configure Tracearr to use an external PostgreSQL database with the TimescaleDB extension enabled. Ensure the database has the required extensions.

```yaml
timescale:
  enabled: false

externalDatabase:
  host: your-db-host.example.com
  port: 5432
  user: tracearr
  database: tracearr

secrets:
  dbPassword: "your-database-password"
```

--------------------------------

### Set Redis Connection String

Source: https://docs.tracearr.com/configuration/environment

Configure the REDIS_URL for Tracearr to connect to your Redis instance. This is used for caching and background job queues.

```bash
REDIS_URL=redis://localhost:6379
```

--------------------------------

### Set Host Directory Permissions

Source: https://docs.tracearr.com/configuration/backup

Ensure the host directory used for backups is owned by the Tracearr user (UID 1001) when using a Docker bind mount. This prevents permission errors.

```bash
sudo chown -R 1001 /path/to/backups
```

--------------------------------

### Copy Backup from Docker Volume

Source: https://docs.tracearr.com/getting-started/installation/supervised

Copy a generated backup from the Tracearr Docker volume to your host filesystem.

```bash
docker cp tracearr:/data/backup ./tracearr-backups
```

--------------------------------

### Accessing Application Logs via Docker Exec

Source: https://docs.tracearr.com/configuration/debug

Use this command to view application error logs directly from the container when running the supervised Docker image.

```bash
docker exec tracearr cat /var/log/supervisor/tracearr-error.log
```

--------------------------------

### Enable Redis Key Prefixing

Source: https://docs.tracearr.com/configuration/environment

Set REDIS_PREFIX to add a namespace to all Redis keys used by Tracearr. This is recommended for shared Redis instances and must end with a delimiter, preferably a colon.

```bash
REDIS_PREFIX=myprefix:
```

--------------------------------

### Upgrade Tracearr Deployment

Source: https://docs.tracearr.com/getting-started/installation/kubernetes

Use this Helm command to upgrade an existing Tracearr deployment. Secrets are automatically preserved. If you change the database password, remember to update it within PostgreSQL as well.

```bash
helm upgrade tracearr ./tracearr --namespace tracearr
```

--------------------------------

### Copy Backup Directory

Source: https://docs.tracearr.com/getting-started/installation

This command copies the entire backup directory from the Tracearr Docker volume to your host filesystem. It's useful for external storage or manual archiving.

```bash
# Copy the entire backup directory from the volume to your host
docker cp tracearr:/data/backup ./tracearr-backups
```

--------------------------------

### Configure External Redis

Source: https://docs.tracearr.com/getting-started/installation/kubernetes

Disable the bundled Redis and configure Tracearr to use an external Redis-compatible server. Ensure your Redis instance is configured with `maxmemory-policy noeviction` to prevent job queue corruption.

```yaml
redis:
  enabled: false

externalRedis:
  url: "redis://your-redis:6379"
```

--------------------------------

### Accessing the Debug Page

Source: https://docs.tracearr.com/configuration/debug

Directly access the Tracearr debug page by navigating to this URL.

```url
http://your-tracearr:3000/debug
```

--------------------------------

### Enable Ingress for External Access

Source: https://docs.tracearr.com/getting-started/installation/kubernetes

Configure ingress settings in your values override to expose Tracearr outside the cluster. Ensure your ingress controller supports HTTP connection upgrades and set appropriate timeouts for WebSocket and SSE connections.

```yaml
ingress:
  enabled: true
  className: nginx  # or traefik, etc.
  annotations:
    nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"
    nginx.ingress.kubernetes.io/proxy-http-version: "1.1"
    cert-manager.io/cluster-issuer: letsencrypt-prod
  hosts:
    - host: tracearr.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: tracearr-tls
      hosts:
        - tracearr.example.com
```

--------------------------------

### Enable DNS Caching

Source: https://docs.tracearr.com/configuration/environment

Set DNS_CACHE_MAX_TTL to a value in seconds to enable DNS caching for outgoing requests. This improves performance by reducing DNS lookups. Caching is disabled if this variable is not set.

```bash
DNS_CACHE_MAX_TTL=3600
```

--------------------------------

### Pull Latest Image and Recreate Container with Docker Compose

Source: https://docs.tracearr.com/upgrading

Use these commands to update Tracearr when using Docker Compose. This pulls the latest image and restarts the container, preserving data.

```bash
docker compose -f docker-compose.pg18.yml pull tracearr
docker compose -f docker-compose.pg18.yml up -d
```

```bash
docker compose -f docker-compose.supervised-example.yml pull tracearr
docker compose -f docker-compose.supervised-example.yml up -d
```

--------------------------------

### Remove Dangling Docker Images

Source: https://docs.tracearr.com/upgrading

After upgrading, use this command to free up disk space by removing unused Docker images. Review the list of images before confirming deletion.

```bash
docker image prune
```

--------------------------------

### Set Base Path for Subpath Deployment

Source: https://docs.tracearr.com/configuration/environment

Configure BASE_PATH if Tracearr is served under a subpath, such as via a reverse proxy. This ensures all internal links and assets are correctly prefixed.

```bash
BASE_PATH=/tracearr
```

--------------------------------

### Generate JWT Secret (Linux/macOS)

Source: https://docs.tracearr.com/getting-started/installation

Generate a random 64-character hexadecimal string for the JWT_SECRET using openssl on Linux or macOS.

```bash
openssl rand -hex 32
```

--------------------------------

### Update Tracearr within LXC Container on Proxmox VE

Source: https://docs.tracearr.com/upgrading

Run this command inside the Tracearr LXC container console to update. It fetches the latest update script and applies the new version.

```bash
update
```

--------------------------------

### Generate Cookie Secret (Windows PowerShell)

Source: https://docs.tracearr.com/getting-started/installation

Generate a random 64-character hexadecimal string for the COOKIE_SECRET using PowerShell on Windows.

```powershell
-join (1..16 | %{'{0:x2}' -f (Get-Random -Max 256)})
```

--------------------------------

### Reset Tracearr Password via Proxmox LXC CLI

Source: https://docs.tracearr.com/faq

Execute this command to reset your Tracearr user password when running in a Proxmox LXC environment. It allows for interactive password input or setting a predefined password.

```bash
node /opt/tracearr/apps/server/scripts/reset-password.ts
```

```bash
node /opt/tracearr/apps/server/scripts/reset-password.ts newpassword123
```

--------------------------------

### Retrieve JWT and Cookie Secrets

Source: https://docs.tracearr.com/getting-started/installation/kubernetes

Retrieve the auto-generated JWT and cookie secrets from the Kubernetes secret. Back up these secrets if you plan to reinstall to avoid invalidating user sessions.

```bash
kubectl get secret tracearr -n tracearr -o jsonpath='{.data.JWT_SECRET}' | base64 -d
```

```bash
kubectl get secret tracearr -n tracearr -o jsonpath='{.data.COOKIE_SECRET}' | base64 -d
```

--------------------------------

### Disable IPv6 in Docker Compose

Source: https://docs.tracearr.com/faq

Add sysctls to your Docker Compose file to disable IPv6 within the Tracearr container, resolving potential connection issues with media servers.

```yaml
services:
  tracearr:
    image: ghcr.io/connorgallopo/tracearr:latest
    # ... your existing config ...
    sysctls:
      - net.ipv6.conf.all.disable_ipv6=1
```

--------------------------------

### Reset Tracearr Password via Docker CLI

Source: https://docs.tracearr.com/faq

Use this command to reset your Tracearr user password when running in a Docker container. It supports both interactive mode for manual password entry and non-interactive mode for setting a specific password.

```bash
docker exec -it tracearr node apps/server/scripts/reset-password.ts
```

```bash
docker exec -it tracearr node apps/server/scripts/reset-password.ts newpassword123
```
Tokens:
Raw