Creating Apps for Runtipi

A step-by-step guide to build, test, and submit an app.

1) Understand the app model

• Each app declares services, environment, volumes, and routing
• The config.json defines metadata and install-time inputs
• The preferred app source file is docker-compose.yml with x-runtipi metadata — see the Dynamic Compose Reference
• The config.json reference: config.json options

2) Scaffold your app

• Start from a minimal docker-compose.yml for your service(s)
• Use x-runtipi.is_main and x-runtipi.internal_port for the main web service instead of writing Traefik labels by hand
• Map persistent data to a volume

3) Define config.json

• Name, description, category
• Required environment variables (with safe defaults if possible)
• Ports, install form fields, and compatibility metadata

4) Test locally

• Validate your config.json and dynamic compose file against the docs references
• Add the app to a test app store or custom app store and install it in a local Runtipi instance
• Verify install, startup, logs, backups, and update behavior before submission

5) Submit to the app store

• Follow the repository contribution guidelines
• Provide screenshots, a short description, and setup notes
• Expect a quick review cycle for clarity and security

Next Steps

• Example apps (browse the store)
• Dynamic Compose Reference — all x-runtipi options
• config.json Reference — app metadata and form fields
• Create your own App Store — step-by-step tutorial