Runtipi

https://runtipi.io/docs
Admin
Runtipi is a platform designed to simplify homeserver management, providing tools for installing,...
Tokens:51,957
Snippets:888
Trust Score:8.1
Update:1 week ago
Show doc for...
Tokens:
Raw
### Start app example

Source: https://runtipi.io/docs/reference/using-the-cli

Example of starting the code-server app from the 'migrated' store.

```bash
./runtipi-cli app start code-server:migrated
```

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

### Start all installed apps

Source: https://runtipi.io/docs/reference/using-the-cli

Starts all installed apps.

```bash
./runtipi-cli app start-all
```

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

### Install Tailscale on VPS

Source: https://runtipi.io/docs/security/vps-security

Commands to install and start Tailscale on the VPS. Run these on the server to set up the VPN connection.

```bash
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up
```

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

### Start your instance

Source: https://runtipi.io/docs/reference/breaking-updates

Starts the Runtipi instance using the new CLI.

```bash
sudo ./runtipi-cli start

```

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

### Start Runtipi on second server

Source: https://runtipi.io/docs/guides/backup-and-restore

Navigates into the runtipi folder and starts Runtipi using the CLI. Ensure Docker is installed before running this command.

```bash
cd runtipi && sudo ./runtipi-cli start
```

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

### Add app store example

Source: https://runtipi.io/docs/reference/using-the-cli

Example of adding a custom app store from a GitHub repository.

```bash
./runtipi-cli appstore add my-store https://github.com/user/my-appstore
```

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

### Start development stack with bun run start:dev

Source: https://runtipi.io/docs/developers/contributing/running-locally

Starts the development stack from the repository root. After running, visit http://localhost:3000 in your browser.

```bash
bun run start:dev
```

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

### Restore app example

Source: https://runtipi.io/docs/reference/using-the-cli

Example of restoring the code-server app from a backup file.

```bash
./runtipi-cli app restore code-server:migrated backup-20241026-120000.tar.gz
```

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

### Start Runtipi instance

Source: https://runtipi.io/docs/reference/breaking-updates

Starts the Runtipi instance using the new CLI.

```bash
./runtipi-cli start
```

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

### Install Runtipi with curl

Source: https://runtipi.io/docs/quick-start

Copy and paste this command into your server terminal to download and install Runtipi along with Docker (if not already installed). The process takes 2-5 minutes.

```bash
curl -L https://setup.runtipi.io | bash
```

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

### List installed apps

Source: https://runtipi.io/docs/reference/using-the-cli

Lists all installed apps.

```bash
./runtipi-cli installed
```

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

### Install dependencies with bun install

Source: https://runtipi.io/docs/developers/contributing/running-locally

Run this command from the repository root to install all project dependencies using bun workspaces.

```bash
bun install
```

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

### Start Runtipi instance

Source: https://runtipi.io/docs/reference/using-the-cli

Starts the Runtipi instance and all services. Supports optional --env-file and --no-permissions flags.

```bash
sudo ./runtipi-cli start [--env-file <path>] [--no-permissions]
```

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

### Update Runtipi examples

Source: https://runtipi.io/docs/reference/using-the-cli

Examples for updating to the latest version and to a specific version (v2.0.7).

```bash
# Update to latest version
sudo ./runtipi-cli update latest
 
# Update to specific version
sudo ./runtipi-cli update v2.0.7
```

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

### Example settings.json file

Source: https://runtipi.io/docs/guides/custom-settings

Example configuration file for custom settings. Place this file at runtipi/state/settings.json to persist changes across restarts. The content must be valid JSON.

```json
{
  "dnsIp": "9.9.9.9",
  "domain": "mydomain.com"
}
```

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

### Start Fail2Ban service

Source: https://runtipi.io/docs/security/vps-security

Enables Fail2Ban to start on boot and starts the service immediately.

```bash
sudo systemctl enable fail2ban
sudo systemctl start fail2ban
```

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

### Start a specific app

Source: https://runtipi.io/docs/reference/using-the-cli

Starts a specific app identified by <app-id>:<store>.

```bash
./runtipi-cli app start <app-id>:<store>
```

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

### Install Runtipi with sudo using curl

Source: https://runtipi.io/docs/learn/troubleshooting

Use this command to install Runtipi when you encounter 'Permission denied' errors. It must be run with sudo to execute the install script.

```bash
curl -L https://setup.runtipi.io | sudo bash
```

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

### tipi.env override format

Source: https://runtipi.io/docs/guides/custom-environment-variables

Example content for tipi.env. Overrides are written in standard KEY=VALUE format and are applied automatically on every start, restart, and update command.

```plaintext
INTERNAL_IP=192.168.1.100
NGINX_PORT=8080
```

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

### Copy .env.example to .env

Source: https://runtipi.io/docs/developers/contributing/running-locally

Copy the environment example file to create your local configuration.

```bash
cp .env.example .env
```

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

### Quick Example: docker-compose.yml with x-runtipi metadata

Source: https://runtipi.io/docs/reference/dynamic-compose

Minimal dynamic compose example for deploying a web app with automatic Traefik routing, networking, and data persistence. Uses ${APP_DATA_DIR} for volume and ${MYAPP_PASSWORD} for environment variable.

```yaml
services:
  myapp:
    image: myapp:latest
    volumes:
      - ${APP_DATA_DIR}/data:/data
    environment:
      - FOO=bar
      - PASSWORD=${MYAPP_PASSWORD}
    x-runtipi:
      is_main: true
      internal_port: 80
 
x-runtipi:
  schema_version: 2
```

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

### Install and enable UFW

Source: https://runtipi.io/docs/security/vps-security

Commands to update the package list, install UFW, and enable the firewall. Run these as root or with sudo.

```bash
sudo apt update
sudo apt install ufw
sudo ufw enable
```

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

### volumes configuration example

Source: https://runtipi.io/docs/reference/dynamic-compose

Example of the volumes array in the legacy JSON format, showing hostPath, containerPath, readOnly, shared, private, and bind propagation settings.

```json
"volumes": [{
  "hostPath": "/host/path",
  "containerPath": "/container/path",
  "readOnly": false,
  "shared": false,
  "private": false,
  "bind": {
    "propagation": "rprivate"
  }
}]
```

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

### Complete Example: Web App with Database

Source: https://runtipi.io/docs/reference/dynamic-compose

A full example of a web app service with a PostgreSQL database, including healthchecks, dependency conditions, and x-runtipi metadata. The app service depends on the database service being healthy, and both use environment variables for configuration.

```yaml
services:
  app:
    image: myapp:2.1.0
    volumes:
      - ${APP_DATA_DIR}/data:/data
    environment:
      - DATABASE_URL=postgresql://postgres:${MYAPP_DB_PASSWORD}@myapp-db:5432/myapp
      - SECRET_KEY=${MYAPP_SECRET_KEY}
    healthcheck:
      test: curl --fail http://localhost:8080/health || exit 1
      interval: 30s
      timeout: 10s
      retries: 3
    depends_on:
      myapp-db:
        condition: service_healthy
    x-runtipi:
      is_main: true
      internal_port: 8080
 
  myapp-db:
    image: postgres:16
    volumes:
      - ${APP_DATA_DIR}/db:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=myapp
      - POSTGRES_PASSWORD=${MYAPP_DB_PASSWORD}
    healthcheck:
      test: pg_isready -U postgres
      interval: 10s
      timeout: 5s
      retries: 5
 
x-runtipi:
  schema_version: 2
```

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

### Start Tipi with custom env file

Source: https://runtipi.io/docs/reference/release-notes

Use the --env-file flag to override any environment variable when starting Tipi.

```bash
./runtipi-cli start --env-file ./.env.custom
```

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

### Start with relative --env-file

Source: https://runtipi.io/docs/guides/custom-environment-variables

Starts Runtipi with a custom environment file using a relative path. The --env-file flag takes precedence over both default values and the auto-loaded tipi.env.

```bash
sudo ./runtipi-cli start --env-file ./.env.local
```

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

### Start with absolute --env-file

Source: https://runtipi.io/docs/guides/custom-environment-variables

Starts Runtipi with a custom environment file using an absolute path. The --env-file flag takes precedence over both default values and the auto-loaded tipi.env.

```bash
sudo ./runtipi-cli start --env-file /home/pi/.env.local
```

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

### addPorts configuration example

Source: https://runtipi.io/docs/reference/dynamic-compose

Example of the addPorts array in the legacy JSON format, showing how to expose additional ports with containerPort, hostPort, tcp, udp, and interface properties.

```json
"addPorts": [{
  "containerPort": 8080,
  "hostPort": 8080,
  "tcp": true,
  "udp": false,
  "interface": "127.0.0.1"
}]
```

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

### Example settings.json file

Source: https://runtipi.io/docs/guides/customize-compose-and-traefik

Example contents of `runtipi/state/settings.json`. The `persistTraefikConfig` key is set to `false` by default; change it to `true` to keep custom Traefik config on restart.

```json
{
  "dnsIp": "9.9.9.9",
  "listenIp": "10.10.10.5",
  "postgresPort": 5432,
  "appsRepoUrl": "https://github.com/runtipi/runtipi-appstore",
  "domain": "example.com",
  "appDataPath": "/home/runtipi/runtipi",
  "localDomain": "tipi.lan",
  "demoMode": false,
  "guestDashboard": false,
  "allowAutoThemes": true,
  "allowErrorMonitoring": false,
  "persistTraefikConfig": false
}
```

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

### Install Fail2Ban

Source: https://runtipi.io/docs/security/vps-security

Installs Fail2Ban, which monitors logs and automatically bans IPs with too many failed login attempts.

```bash
sudo apt install fail2ban
```

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

### docker-compose.yml example with x-runtipi metadata

Source: https://runtipi.io/docs/learn/apps-and-app-store

Defines the Docker container(s) for an app using standard Compose-like YAML with x-runtipi metadata for routing and app-specific behavior. The example shows an nginx service with is_main and internal_port, and a schema_version of 2.

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

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

### Example of form_fields in config.json

Source: https://runtipi.io/docs/reference/config-json

Shows how to define form fields in config.json to prompt the user for install-time values such as a username and password. Each field specifies type, label, min/max length, required flag, and the environment variable that will receive the value.

```json
{
  "form_fields": [
    {
      "type": "text",
      "label": "Username",
      "max": 50,
      "min": 3,
      "required": true,
      "env_variable": "NEXTCLOUD_ADMIN_USER"
    },
    {
      "type": "password",
      "label": "Password",
      "max": 50,
      "min": 3,
      "required": true,
      "env_variable": "NEXTCLOUD_ADMIN_PASSWORD"
    }
  ]
}
```

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

### Create tipi.env with nano

Source: https://runtipi.io/docs/guides/custom-environment-variables

Creates or edits the auto-loaded environment file. The file must be named tipi.env and reside in the user-config directory of the Runtipi installation.

```bash
nano /path/to/runtipi/user-config/tipi.env
```

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

### Prepare environment

Source: https://runtipi.io/docs/reference/using-the-cli

Prepares the environment without starting containers. Checks permissions, copies files, and generates configuration. Supports optional --env-file and --no-permissions flags.

```bash
sudo ./runtipi-cli prepare [--env-file <path>] [--no-permissions]
```

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

### Create the docker-compose.yml with x-runtipi metadata

Source: https://runtipi.io/docs/guides/dynamic-compose-guide

Start with the top-level x-runtipi metadata and an empty services block. The schema_version must be 2 and dynamic_config must be set to true in the app's config.json.

```yaml
services:
  # services go here

x-runtipi:
  schema_version: 2
```

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

### healthCheck configuration example

Source: https://runtipi.io/docs/reference/dynamic-compose

Example of the healthCheck object in the legacy JSON format, specifying test command, retries, interval, timeout, startInterval, and startPeriod.

```json
"healthCheck": {
  "test": "curl --fail http://localhost",
  "retries": 3,
  "interval": "30s",
  "timeout": "10s",
  "startInterval": "5s",
  "startPeriod": "30s"
}
```

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

### List configured app stores

Source: https://runtipi.io/docs/reference/using-the-cli

Lists all configured app stores.

```bash
./runtipi-cli appstore list
```

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

### Create a backup of an app

Source: https://runtipi.io/docs/reference/using-the-cli

Creates a backup of an app.

```bash
./runtipi-cli app backup <app-id>:<store>
```

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

### Create auto-update.sh script

Source: https://runtipi.io/docs/guides/auto-update-with-cron

Bash script that checks for a new Runtipi release, backs up the current installation, and updates it. Change the 'runtipi_path' variable to your installation path. The script compares major versions and only updates if the major version matches and the latest version is newer.

```bash
#!/usr/bin/env bash
 
compare_major_version() {
    local major_version1=$(echo "$1" | cut -d. -f1)
    local major_version2=$(echo "$2" | cut -d. -f1)
 
    if [[ "$major_version1" == "$major_version2" ]]; then
        return 0 # Success (major versions match)
    else
        return 1 # Failure (major versions differ)
    fi
}
 
# IMPORTANT: Change this to the path of your Runtipi installation.
runtipi_path="/opt/runtipi"
 
# Validate Runtipi path and VERSION file
if [[ ! -d "$runtipi_path" ]]; then
    echo "Error: Runtipi path '$runtipi_path' not found or is not a directory." >&2
    echo "Please correct the 'runtipi_path' variable in the script." >&2
    exit 1
fi
version_file="$runtipi_path/VERSION"
if [[ ! -f "$version_file" ]]; then
    echo "Error: Version file '$version_file' not found." >&2
    exit 1
fi
 
# Get Current Version of Runtipi
current_version=$(cat "$version_file")
if [[ -z "$current_version" ]]; then
    echo "Error: Could not read current version from '$version_file'." >&2
    exit 1
fi
echo "Current version: $current_version"
 
# Get the latest release information from GitHub API
echo "Fetching latest release info..."
latest_release=$(curl -fsSL \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/repos/runtipi/runtipi/releases/latest)
 
if [[ $? -ne 0 || -z "$latest_release" ]]; then
    echo "Error: Failed to fetch release information from GitHub." >&2
    exit 1
fi
 
tag_name=$(echo "$latest_release" | grep -o '"tag_name": "[^"]*' | cut -d'"' -f4)
 
if [[ -z "$tag_name" ]]; then
    echo "Error: Could not extract tag_name from GitHub API response." >&2
    exit 1
fi
echo "Latest version: $tag_name"
 
compare_major_version "$tag_name" "$current_version"
major_version_match=$?
 
is_newer=1
if [[ "$tag_name" != "$current_version" ]]; then
    latest_sorted=$(printf '%s\n%s\n' "$current_version" "$tag_name" | sort -V | tail -n1)
    if [[ "$latest_sorted" == "$tag_name" ]]; then
        is_newer=0
    fi
fi
 
if [[ $major_version_match -eq 0 ]] && [[ $is_newer -eq 0 ]]; then
    echo "A new compatible release is available: $tag_name"
 
    runtipi_cli="$runtipi_path/runtipi-cli"
    if [[ ! -x "$runtipi_cli" ]]; then
        echo "Error: Runtipi CLI '$runtipi_cli' not found or not executable." >&2
        exit 1
    fi
 
    cd "$runtipi_path" || exit 1
 
    echo "Backing up current version..."
    backup_dir="backups"
    backup_file="runtipi-backup-$current_version.tar.gz"
    backup_path="$backup_dir/$backup_file"
 
    if [ ! -d "$backup_dir" ]; then
        mkdir -p "$backup_dir"
    fi
 
    echo "Creating backup: $backup_path"
 
    if tar -czf "$backup_path" --exclude=./media --exclude=./"$backup_dir" .; then
        echo "Backup successful."
        echo "Starting update..."
 
        if "$runtipi_cli" update latest; then
             echo "Update command finished."
        else
             echo "Error: Runtipi update command failed. Check output above." >&2
             echo "Restore from backup '$backup_path' if necessary." >&2
             exit 1
        fi
    else
        echo "Error: Failed to create backup archive '$backup_path'." >&2
        exit 1
    fi
else
    if [[ "$tag_name" == "$current_version" ]]; then
        echo "You are already running the latest version ($current_version)."
    elif [[ $major_version_match -ne 0 ]]; then
        echo "No new release found. Major version mismatch (Current: $current_version, Latest: $tag_name)."
    else
        echo "No new release found."
    fi
fi
 
echo "Update check complete."
exit 0
```

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

### Create user-config folders for Jellyfin and Pihole

Source: https://runtipi.io/docs/guides/customize-app-config

Commands to create the user-config directory structure inside runtipi, matching the app store and app names. Replace <app-store> with your app store name (e.g., 'migrated' for the default).

```bash
cd runtipi
mkdir -p user-config/<app-store>/jellyfin
mkdir -p user-config/<app-store>/pihole

```

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

### Update system packages

Source: https://runtipi.io/docs/security/vps-security

Updates the package list and upgrades all installed packages.

```bash
sudo apt update && sudo apt upgrade
```

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

### Download new CLI for v3.0.0

Source: https://runtipi.io/docs/reference/breaking-updates

Downloads and extracts the new CLI binary. Replace <asset-name> with the appropriate asset for your architecture.

```bash
curl -sSL https://github.com/runtipi/runtipi/releases/download/v3.0.0/<asset-name> | tar -xz
```

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

### Enable cron service

Source: https://runtipi.io/docs/guides/auto-backup-apps

Command to enable and start the cron service on systemd-based systems.

```bash
sudo systemctl enable --now cron.service
```

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

### Restart Runtipi services

Source: https://runtipi.io/docs/reference/using-the-cli

Stops and starts Runtipi services. Supports optional --env-file and --no-permissions flags.

```bash
sudo ./runtipi-cli restart [--env-file <path>] [--no-permissions]
```

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

### Update Runtipi to a specific version

Source: https://runtipi.io/docs/reference/using-the-cli

Updates Runtipi to a specific version. Downgrading may break the installation; always backup before downgrading.

```bash
sudo ./runtipi-cli update <version> [--env-file <path>] [--no-permissions]
```

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

### Download update script for 3.0.0 to 4.0.0

Source: https://runtipi.io/docs/reference/breaking-updates

Downloads the migration script from the Runtipi repository to the current directory. Run this in the runtipi directory before executing the script.

```bash
curl -sSL https://raw.githubusercontent.com/runtipi/runtipi/master/scripts/update-3.0.0-to-4.0.0.sh -o update_script.sh
```

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

### Restart Jellyfin and Pihole apps

Source: https://runtipi.io/docs/guides/customize-app-config

Commands to stop and start the Jellyfin and Pihole apps using the runtipi-cli, specifying the app store in the app identifier.

```bash
./runtipi-cli app stop jellyfin:<app-store>
./runtipi-cli app start jellyfin:<app-store>
./runtipi-cli app stop pihole:<app-store>
./runtipi-cli app start pihole:<app-store>

```

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

### Display CLI version

Source: https://runtipi.io/docs/reference/using-the-cli

Shows version number, commit hash, and build date.

```bash
./runtipi-cli version
```

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

### Access the dashboard URL

Source: https://runtipi.io/docs/quick-start

Once installation is complete, open your browser and navigate to this URL, replacing 'your-server-ip' with your server's local IP address (e.g., 192.168.1.100).

```text
http://your-server-ip
```

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

### List available backups

Source: https://runtipi.io/docs/reference/using-the-cli

Lists available backups for an app.

```bash
./runtipi-cli app list-backups <app-id>:<store>
```

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

### Retention configuration values

Source: https://runtipi.io/docs/guides/auto-backup-apps

Variables in the backup script that control how many backup cycles are kept for each frequency. For example, a daily backup is deleted after 3 days.

```bash
dailyRetention=3
weeklyRetention=3
monthlyRetention=3
```
Tokens:
Raw