Apps & the App Store

Understanding how Runtipi apps work will help you make the most of the platform and even create your own apps.

What is an app in Runtipi?

A Runtipi app is a pre-configured Docker container (or set of containers) that can be installed with one click. Think of it like an app on your smartphone, but running on your server instead.

Each app includes:

• The software itself (e.g., Nextcloud, Jellyfin, etc.)
• Pre-configured settings opinionated, that work out of the box
• Automatic networking via Traefik
• Data persistence so your files survive restarts and can be safely backed up
• Optional customization for advanced users

The App Store

An app store is a collection of apps that you can browse and install from the Runtipi dashboard. The runtipi team manages an official “default” app store, but anyone can create their own custom app store repository and add apps to it.

You can see this as a marketplace of blueprints for self-hosted applications that are ready to run with minimal setup and that you can customize as needed.

App Store repository

An App Store is actually a separate git repository: runtipi/runtipi-appstore

When you browse apps in Runtipi, it loads apps from one or more configured app store repositories. Each app is uniquely identified by its app ID plus the store slug.

App Architecture

Every app in the store has this structure:

• app-name
  • config.json
  • docker-compose.yml
  • metadata
    • logo.jpg
    • description.md

config.json

Defines the app’s:

• Name and description
• Version
• Configurable options (shown in the UI)
• Architecture support (x86/ARM)
• And more…

For more options, check out the full specs config.json.

{
  "name": "Nextcloud",
  "port": 8080,
  "available": true,
  "exposable": true,
  "form_fields": [
    {
      "type": "text",
      "label": "Admin Username",
      "env_variable": "NEXTCLOUD_ADMIN_USER"
    }
  ]
}

docker-compose.yml

Defines the actual Docker container(s) to run the app. Runtipi uses a standard Compose-like YAML file with x-runtipi metadata for routing and app-specific behavior.

services:
  nginx:
    image: nginx:1.29.2
    x-runtipi:
      is_main: true
      internal_port: 80
 
x-runtipi:
  schema_version: 2

For a full reference of x-runtipi options, see the Dynamic Compose Reference.

App lifecycle

Running

• App runs continuously in the background
• Data is persisted to app-data/<store-slug>/<app-name>/
• You can start, stop, or restart anytime
• Logs are available for debugging

Updates

• When the app store has a new version, Runtipi notifies you
• You can update with one click
• Data and config are preserved during updates
• Rollback to a backup if needed

Uninstallation

• Runtipi stops the containers
• Container images are removed
• Your data gets deleted in app-data/

App data & persistence

All app data is stored in the app-data/ directory in your Runtipi installation:

• runtipi
  • app-data
    • migrated
      • nextcloud
        • data
        • config
        • database
    • my-store
      • jellyfin
        • media
        • config

Key Points:

• This directory survives app restarts and updates
• Back this up regularly - it’s your actual data
• Can be very large (depending on apps)
• Each app has its own isolated folder

Architecture support

Not all apps work on all processor architectures:

x86_64 / amd64

• Most common for desktops and servers
• Most apps supported

ARM64

• Raspberry Pi 4/5, some SBCs
• Many apps supported
• Some apps unavailable (Runtipi hides them automatically)