Foxws
Pods

Application Manifest

Application manifest (pods.yml)

A repository can tell Pods how to install it with a pods.yml in its root, or in a directory per application. When you add an application from Git, Pods reads it to offer the repository's Quadlet directories, fill in the application name, and explain and fill in the secrets the units need. It never changes the Quadlet files: they stay installable with plain podman quadlet install, and a repository without pods.yml installs as before.

version: 1 # Pods ignores manifests of a version it doesn't know
name: hello # the default application name
label: hello # shown in the catalog, like the keys below
description: Self-hosted video library
author: Example
icon: i-lucide-film # a Lucide icon
category: Media
website: https://hello.example.com
repository: https://github.com/example/hello # its source code
notes: Shown before installing.

sources: # Quadlet directories to choose from, relative to this pods.yml
    production:
        path: containers/quadlets/production
        description: The published image

secrets: # how to ask for the secrets the units use
    hello-env:
        description: Your .env file
        format: dotenv # a text area; other secrets can read keys from it
    hello-pgsql-password:
        from: hello-env # filled in from DB_PASSWORD in the .env above
        key: DB_PASSWORD
    hello-app-key:
        generate: true # filled in with a random value

after_install: # commands to run once the units are up, from the application page
    install:
        label: Install hello
        container: hello # the container's Quadlet, without .container
        user: docker # optional, like workdir
        command: php artisan app:install --no-interaction # split on whitespace
    admin:
        label: Create the first admin
        container: hello
        command: php artisan users:create --super-admin --password-stdin --no-interaction
        inputs: # asked for before the step runs
            name:
                option: --name
            email:
                type: email # text (the default), email or password
                option: --email # passed as --email=VALUE
            password:
                type: password # an input without an option goes on stdin

after_update: # commands to run after each update, once the new units are up; names differ from after_install's
    migrate:
        label: Migrate the database
        container: hello
        user: docker
        command: php artisan migrate --force --no-interaction

routes: # upstreams the Pods proxy can give a hostname; Pods asks for the hostnames
    app:
        upstream: systemd-hello:8000 # a container and its port
        description: The web app # the first route is the main one, unless another says main: true
    ws:
        upstream: systemd-hello-reverb:6001
        via: main # optional: go where the main route goes, for an app that routes its own hostnames

ondemand: # fills in the on-demand switch; the keys match lpod's ondemand status
    port: 8000 # the socket on the host
    app_port: 8000 # inside the app container, read from its unit when left out
    idle_timeout: 10min
    workers: [hello-horizon] # keep running until the idle check says there's no work
    idle_check:
        container: hello-horizon
        user: docker
        command: php /app/artisan app:idle
    schedule: # runs schedule:run only at these minutes, in UTC
        container: hello-schedule
        at: ['*:00', '01:00']
        environment:
            APP_COMMAND: php /app/artisan schedule:run

timers: # containers a systemd timer starts on a schedule; the keys are the directives they become
    backup: # lpod writes APP-NAME.timer, here hello-backup.timer
        description: Backs up the database
        container: hello-backup # a container Quadlet of the app that runs once and exits (Type=oneshot)
        on_calendar: daily # OnCalendar=, or a list of calendar events
        persistent: true # Persistent=: catch up on a run missed while the host was off
        randomized_delay_sec: 30min # RandomizedDelaySec=
        timeout_start_sec: infinity # TimeoutStartSec= for the container, in a drop-in

Every key is optional. When you fetch a directory, Pods reads the nearest pods.yml: the one in that directory, or else in a directory above it. Secret values stay in the browser until you install, and go to the host on stdin like any other secret. After an update, the application page asks for the new release's after_update steps, which take inputs like setup steps, and only counts a step as done once it ran since that update. A step's inputs aren't stored; at most one input goes on stdin, and a password always does, so it never shows in the arguments. A manifest Pods can't read is shown as a warning and ignored, so the files can still be installed.

Pods sets up the timers after installing and after each update, so they follow the release: a timer the new pods.yml no longer names is removed. The application page has a Timers card with each timer's schedule, next and last run, and Run now. A timer starts what its container Requires=, so it also wakes an on-demand application, which sleeps again after its idle timeout. timers are for jobs that live on the host; a Laravel scheduler stays in ondemand.schedule, since it only runs from a timer while the application is on demand.

The applications in foxws/quadlets each have a pods.yml to start from. Backup hints are planned; see the roadmap.

Catalog

The Install application page lists the applications of the repositories in config/catalog.php, foxws/quadlets by default. Every directory at such a repository's root with a pods.yml is one application, such as mariadb/pods.yml with production and development sources next to it. The host clones the repository to read them, and Pods keeps the list for a few minutes.