Rediflow
English ▾

Deploy on containerized Ubuntu 24.04 desktop (nested containers)

This guide covers deploying Rediflow on an Ubuntu 24.04.2 desktop that itself runs inside a container (e.g. LXD, LXC). Both the database and app run on the same host via Podman (nested containers).

Prerequisites

  • Outer container: Ubuntu 24.04.2 desktop (LXD, LXC, or similar)
  • Outer container configured with security.nesting=true and security.privileged=true

One-time setup of the outer container

If using LXD:

lxc config set <container-name> security.nesting=true
lxc config set <container-name> security.privileged=true
lxc restart <container-name>

Installation inside Ubuntu

  1. Install Podman and dependencies:

    sudo apt update
sudo apt install -y podman podman-compose iptables-nft fuse-overlayfs

  2. (Optional) If overlay storage fails, edit /etc/containers/storage.conf and uncomment:

    [storage.options.overlay]
mount_program = "/usr/bin/fuse-overlayfs"

Deployment

Follow Deploy QA and production using compose.deploy-prod.yml or compose.deploy-qa.yml. The compose stack runs both DB and app on the same host.

Test script

A script to verify the installation in this environment is available:

./scripts/test-containerized-ubuntu-install.sh

Logs are written to tmp/containerized-ubuntu-install.log. See Troubleshooting for common issues.

Troubleshooting

Issue Resolution
"insufficient UIDs/GIDs" Use rootful Podman (sudo podman) or ensure outer container is privileged
Overlay mount errors Enable fuse-overlayfs in storage.conf
Port binding fails Ensure ports 5000/5001 and 5432 (or POSTGRES_PORT) are not blocked by the outer host
Registry login podman login registry.gitlab.com if image is private
Port already in use Stop existing Rediflow stack or use a different POSTGRES_PORT in .env.qa
"container name already in use" Run podman compose -f compose.deploy-qa.yml down from the deploy directory, or re-run the test script (it cleans up first)
App not responding immediately Gunicorn may take a few seconds to start; the test script retries for up to ~25 seconds
TTY warning on migrate Harmless when running non-interactively; migrations still run correctly

Test run log (developer stage)

The test script was executed on a host running Linux Mint 22.3 (Ubuntu-based) with Podman 4.9.3. Results:

Step Outcome
OS check Passed (Ubuntu-derived)
Basic container run Passed
Registry pull Passed (image pulled successfully)
Compose up Passed (DB and app started)
Migrations Passed (all migrations applied)
App health check Passed after retries

Observed issues and resolutions:

  1. Container name conflict — When rediflow-app-qa or rediflow-db-qa already existed from a prior run, podman run failed with "container name already in use". Resolution: The script now runs podman compose down before up to clean up any previous test stack.

  2. podman-compose project naming — podman-compose 1.0.6 uses the working directory name as the project name (e.g. rediflow-deploy-test), creating volumes like rediflow-deploy-test_rediflow_qa_pgdata. This is expected.

  3. TTY warning — podman compose run --rm app-qa rediflow migrate head produced "The input device is not a TTY" when run non-interactively. This is harmless; migrations completed successfully.

See also