Skip to main content

​
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

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.

​
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.

Build docs developers (and LLMs) love

Get started for freeTalk to us