Upgrading

Upgrade tuliprox safely across Docker, binary, and source installations.

Before you upgrade

1. Read the changelog

   Check the CHANGELOG for breaking changes before upgrading. Breaking changes in tuliprox include configuration renames, data format changes, and storage migrations that require manual steps.

2. Back up your configuration

   Ensure your config files are backed up. If you have configured backup_dir, the Web UI writes config snapshots there automatically:

   backup_dir: ./data/backup
   

   You can also copy the files manually:

   cp -r /home/tuliprox/config /home/tuliprox/config.bak
   
3. Note your current version

   Record the version you are running before upgrading so you can roll back if needed.

Upgrade methods

Docker

1. Pull the new image

   docker pull ghcr.io/euzu/tuliprox-alpine:latest
   

   Or for a specific version tag:

   docker pull ghcr.io/euzu/tuliprox-alpine:1.2.3
   
2. Restart the container

   docker compose down
   docker compose up -d
   

   If you are not using Compose:

   docker stop tuliprox
   docker rm tuliprox
   docker run -d --name tuliprox \
     -v /home/tuliprox/config:/app/config \
     -v /home/tuliprox/data:/app/data \
     -p 8901:8901 \
     ghcr.io/euzu/tuliprox-alpine:latest
   
3. Verify startup

   Check the container logs for errors:

   docker logs -f tuliprox
   

   Confirm the Web UI loads and streams are accessible.

Binary

1. Stop the running service

   systemctl stop tuliprox
   

   Or, if running manually, send SIGTERM to the process.

2. Replace the binary

   Download the new binary from the GitHub releases page and replace the existing one:

   cp tuliprox /usr/local/bin/tuliprox
   chmod +x /usr/local/bin/tuliprox
   
3. Start the service

   systemctl start tuliprox
   

   Check the journal for startup errors:

   journalctl -u tuliprox -f
   

From source

1. Pull the latest code

   git pull origin main
   

   If you track the develop branch:

   git pull origin develop
   
2. Rebuild

   cargo build --release --bin tuliprox
   
3. Restart the process

   Stop the running instance and start the newly built binary:

   ./target/release/tuliprox -s -c config/config.yml -i config/source.yml
   

Hot reload vs full restart

For certain changes, a full restart is not required. The config_hot_reload option enables live reloading of mapping files and API-proxy configuration:

config_hot_reload: true

When enabled, tuliprox watches mapping.yml (or the configured mapping_path directory) and api-proxy.yml for changes and applies them without stopping the server.

Hot reload covers mapping rules and API-proxy users. Changes to config.yml itself — such as reverse_proxy, api, log, or messaging settings — require a full restart to take effect.

Breaking changes

Breaking changes have appeared between major versions. Before upgrading, check the CHANGELOG for entries marked Breaking Changes. Past examples include:

• working_dir renamed to storage_dir
• threads (integer) renamed to process_parallel (boolean)
• Storage format changes requiring the data/ directory to be cleared and playlists re-fetched
• Input batch URLs changed from file:// to the batch:// scheme
• library.metadata.path moved to metadata_update.cache_path
• dns.resolved removed from source.yml; resolved IPs now persisted in {storage_dir}/provider_dns_resolved.json
• forced_retry_interval_secs removed
• rewrite_secret added as a mandatory field under reverse_proxy

If the CHANGELOG notes a data format change, clear your storage_dir after upgrading and trigger a fresh playlist update. Plex, Jellyfin, and other clients may need to re-scan their libraries after virtual IDs are reassigned.

Configuration migration notes

After reviewing the changelog, update your config.yml for any renamed or restructured fields. A common pattern is to run the server once with log_level: debug after upgrading to surface any unrecognised or deprecated configuration keys:

log:
  log_level: debug

Tuliprox logs warnings for unknown keys, making it straightforward to identify fields that need renaming.