Support (rootless) podman for the development workflow

Author: dutow

.github/workflows/dev-setup.yml

@@ -27,15 +27,15 @@ jobs:
         run: |
           echo "Waiting for Rails to start..."
           for i in {1..60}; do
-            if docker compose -f docker-compose.dev.yml exec -T web curl -fs http://localhost:3000/up 2>/dev/null; then
+            if docker compose -f compose.dev.yml exec -T web curl -fs http://localhost:3000/up 2>/dev/null; then
               echo "Rails is healthy!"
               exit 0
             fi
             echo "Attempt $i/60 - waiting 5s..."
             sleep 5
           done
           echo "Rails failed to start. Showing logs:"
-          docker compose -f docker-compose.dev.yml logs --tail=200 web db
+          docker compose -f compose.dev.yml logs --tail=200 web db
           exit 1
 
       - name: Run db-reset while stack is running
@@ -45,15 +45,15 @@ jobs:
         run: |
           echo "Waiting for web to restart after db-reset..."
           for i in {1..30}; do
-            if docker compose -f docker-compose.dev.yml exec -T web curl -fs http://localhost:3000/up 2>/dev/null; then
+            if docker compose -f compose.dev.yml exec -T web curl -fs http://localhost:3000/up 2>/dev/null; then
               echo "Web is healthy after db-reset!"
               exit 0
             fi
             echo "Attempt $i/30 - waiting 5s..."
             sleep 5
           done
           echo "Web failed to restart. Showing logs:"
-          docker compose -f docker-compose.dev.yml logs --tail=200 web db
+          docker compose -f compose.dev.yml logs --tail=200 web db
           exit 1
 
       - name: Run RSpec tests

Dockerfile.dev Containerfile.devDockerfile.dev renamed to Containerfile.dev

@@ -1,5 +1,5 @@
 ARG RUBY_VERSION=3.4
-FROM ruby:${RUBY_VERSION}
+FROM docker.io/library/ruby:${RUBY_VERSION}
 
 ENV RAILS_ENV=development \
     NODE_ENV=development \
@@ -21,5 +21,5 @@ RUN npm install
 
 EXPOSE 3000
 
-ENTRYPOINT ["./bin/docker-entrypoint"]
+ENTRYPOINT ["./bin/container-entrypoint"]
 CMD ["./bin/rails", "server", "-b", "0.0.0.0"]

Makefile

@@ -1,4 +1,5 @@
-COMPOSE ?= docker compose --env-file .env.development -f docker-compose.dev.yml
+ENGINE  ?= $(shell command -v podman >/dev/null 2>&1 && echo podman || echo docker)
+COMPOSE ?= $(ENGINE) compose --env-file .env.development -f compose.dev.yml
 
 .PHONY: dev dev-detach down shell console test imap logs db-migrate db-reset db-import stats psql sim-email-once sim-email-stream
 

README.md

@@ -1,39 +1,35 @@
 # Hackorum
 
-Rails 8 app backed by Postgres. Use the Docker-based development setup below for a quick start; production deploy lives under `deploy/` with its own `README`.
+Rails 8 app backed by Postgres. Use the containerised development setup below for a quick start; production deploy lives under `deploy/` with its own `README`.
 
 Live application is available at https://hackorum.dev
 
-## Development (Docker)
+## Development
+
+Both Docker and Podman (rootless) are supported. The Makefile auto-detects which runtime is available (preferring Podman). Override with `ENGINE=docker` or `ENGINE=podman`.
+
 1) Copy the sample env and adjust as needed:
 ```bash
 cp .env.development.example .env.development
 ```
 2) Build and start the stack (web + Postgres):
 ```bash
-docker compose -f docker-compose.dev.yml up --build
+make dev
 ```
 * App: http://localhost:3000
 * Postgres: localhost:15432 (user/password: hackorum/hackorum by default)
 * Emails sent by the application use `letter_opener`, will be opened by the browser automatically
-* If you run into a Postgres data-dir warning, clear the old volume: `docker volume rm hackorum_db-data`
+* If you run into a Postgres data-dir warning, clear the old volume: `docker volume rm hackorum_db-data` (or `podman volume rm hackorum_db-data`)
 
 Useful commands:
-* Shell: `docker compose -f docker-compose.dev.yml exec web bash`
-* Rails console: `docker compose -f docker-compose.dev.yml exec web bin/rails console`
-* Migrations/seeds: `docker compose -f docker-compose.dev.yml exec web bin/rails db:prepare`
-* Tests: `docker compose -f docker-compose.dev.yml exec web bundle exec rspec`
+* Shell: `make shell`
+* Rails console: `make console`
+* Migrations/seeds: `make db-migrate` (or run arbitrary commands via `make shell`)
+* Tests: `make test`
 * Import a public DB dump: `make db-import DUMP=/path/to/public-YYYY-MM.sql.gz`
 * If you need private table definitions too, apply `private-schema-YYYY-MM.sql.gz` after the import:
-  `gzip -cd /path/to/private-schema-YYYY-MM.sql.gz | docker compose -f docker-compose.dev.yml exec -T db psql`
-
-Makefile shortcuts:
-* `make dev` / `make dev-detach` / `make down`
-* `make shell` / `make console` / `make logs`
-* `make test`
-* `make db-migrate` / `make db-reset`
-* `make db-import`
-* `make psql`
+  `gzip -cd /path/to/private-schema-YYYY-MM.sql.gz | make psql`
+* Other targets: `make dev-detach` / `make down` / `make logs` / `make db-reset` / `make psql`
 
 Public database dumps (schema + public data) are published at https://dumps.hackorum.dev/
 
@@ -51,10 +47,9 @@ Makefile shortcuts:
 The "production" IMAP worker which pulls actual mailing list messages from an IMAP label can be also run locally.
 
 ```bash
-docker compose -f docker-compose.dev.yml --profile imap up --build
+make imap
 ```
 Configure IMAP via `.env.development` (`IMAP_USERNAME`, `IMAP_PASSWORD`, `IMAP_MAILBOX_LABEL`, `IMAP_HOST`, `IMAP_PORT`, `IMAP_SSL`).
-Shortcut: `make imap`
 
 Host, Port and ssl settings default to the gmail imap server.
 

bin/docker-entrypoint bin/container-entrypointbin/docker-entrypoint renamed to bin/container-entrypoint

@@ -1,11 +1,11 @@
 services:
   db:
-    image: postgres:18
+    image: docker.io/library/postgres:18
     env_file:
       - .env.development
     volumes:
       - db-data:/var/lib/postgresql
-      - ./deploy/postgres/init/01_pg_stat_statements.sql:/docker-entrypoint-initdb.d/01_pg_stat_statements.sql:ro
+      - ./deploy/postgres/init/01_pg_stat_statements.sql:/docker-entrypoint-initdb.d/01_pg_stat_statements.sql:ro,z
     ports:
       - "15432:5432"
     command:
@@ -16,23 +16,23 @@ services:
         "-c", "pg_stat_statements.track=all"
       ]
     healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-hackorum} -d ${POSTGRES_DB:-hackorum_development}"]
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-hackorum} -d ${POSTGRES_DB:-hackorum_development} -h /var/run/postgresql"]
       interval: 10s
       timeout: 5s
       retries: 5
 
   web:
     build:
       context: .
-      dockerfile: Dockerfile.dev
+      dockerfile: Containerfile.dev
     env_file:
       - .env.development
     environment:
       RAILS_ENV: ${RAILS_ENV:-development}
       NODE_ENV: ${NODE_ENV:-development}
       HOST: 0.0.0.0
       PORT: ${PORT:-3000}
-      DATABASE_URL: ${DATABASE_URL:-postgresql://${POSTGRES_USER:-hackorum}:${POSTGRES_PASSWORD:-hackorum}@db:5432/${POSTGRES_DB:-hackorum_development}}
+      DATABASE_URL: postgresql://${POSTGRES_USER:-hackorum}:${POSTGRES_PASSWORD:-hackorum}@db:5432/${POSTGRES_DB:-hackorum_development}
       PGHOST: db
       PGPORT: 5432
       PGUSER: ${POSTGRES_USER:-hackorum}
@@ -41,43 +41,43 @@ services:
       SOLID_QUEUE_IN_PUMA: "1"
       FORCE_SSL: ${FORCE_SSL:-false}
     volumes:
-      - .:/app
+      - .:/app:z
       - bundle:/usr/local/bundle
       - node_modules:/app/node_modules
     ports:
       - "${PORT:-3000}:${PORT:-3000}"
     depends_on:
       db:
         condition: service_healthy
-    entrypoint: ["./bin/docker-entrypoint"]
+    entrypoint: ["./bin/container-entrypoint"]
     command: ["./bin/dev"]
 
   imap_worker:
     profiles: ["imap"]
     build:
       context: .
-      dockerfile: Dockerfile.dev
+      dockerfile: Containerfile.dev
     env_file:
       - .env.development
     command: ["bundle", "exec", "ruby", "script/imap_idle.rb"]
     environment:
       RAILS_ENV: ${RAILS_ENV:-development}
-      DATABASE_URL: ${DATABASE_URL:-postgresql://${POSTGRES_USER:-hackorum}:${POSTGRES_PASSWORD:-hackorum}@db:5432/${POSTGRES_DB:-hackorum_development}}
+      DATABASE_URL: postgresql://${POSTGRES_USER:-hackorum}:${POSTGRES_PASSWORD:-hackorum}@db:5432/${POSTGRES_DB:-hackorum_development}
       PGHOST: db
       PGPORT: 5432
       PGUSER: ${POSTGRES_USER:-hackorum}
       PGPASSWORD: ${POSTGRES_PASSWORD:-hackorum}
       PGDATABASE: ${POSTGRES_DB:-hackorum_development}
     volumes:
-      - .:/app
+      - .:/app:z
       - bundle:/usr/local/bundle
     depends_on:
       db:
         condition: service_healthy
 
   psql:
     profiles: ["tools"]
-    image: postgres:18
+    image: docker.io/library/postgres:18
     entrypoint: ["psql", "postgresql://${POSTGRES_USER:-hackorum}:${POSTGRES_PASSWORD:-hackorum}@db:5432/${POSTGRES_DB:-hackorum_development}"]
     env_file:
       - .env.development