bin/plan.md

Install EspoCRM on DesTEngSsv006 (rootless Podman pod)

Goal: create four shell scripts that run EspoCRM as a rootless Podman pod under the local user mkt.

A reference script, create_pod_traefik.sh, is attached. Follow its structure and conventions (the "House style" section below).

Target environment (given — do not provision in the scripts)

• Host: DesTEngSsv006, Debian GNU/Linux 12 (bookworm), Kernel 6.1.0-49-amd64, x86-64.
• Podman 4.3.1, rootless. User mkt exists; subuid/subgid and enable-linger are configured. All scripts run as user mkt.
• Scripts live in /home/mkt/bin (a private git repo, not public, classified as a company secret). Plaintext passwords in the scripts are therefore deliberately acceptable.
• Autostart: Podman 4.3.1 has no Quadlet (introduced in 4.4). Use podman generate systemd --files --new (systemd --user) for autostart. Do not use Quadlet.

House style (mandatory — follow create_pod_traefik.sh)

• Shebang #!/bin/bash, short comment header (who runs it, what it does).
• A block of environment variables at the top (pod name, container names, images, ports, IPs, BIND_DIR, systemd paths).
• Network option exactly as in the reference: NET_OPTS='slirp4netns:allow_host_loopback=true,port_handler=slirp4netns'.
• Data stored as bind mounts under BIND_DIR="$HOME/.local/share/$POD_NAME", passed via -v in the podman command (no named volumes).
• Create the pod guarded with if ! podman pod exists; publish ports on the pod via -p.
• Create containers with podman run -d --name ... --pod "$POD_NAME" -v ... "$IMAGE".
• Generate systemd units with cd "$USER_SYSTEMD_DIR"; podman generate systemd --files --new --name "$POD_NAME".
• Then stop and remove the live pod, and systemctl --user enable --now the generated services (so the systemd-managed instance is what runs in the end).
• Status messages via echo "... (rc=$?)" as in the reference.

Fixed parameters

• Pod name: espocrm_pod.
• Containers: mariadb_ctr (DB), espocrm_ctr (web), espocrm_daemon_ctr (scheduler/cron). No WebSocket container (no live updates).
• Images (pinned, no auto-updates):
  • EspoCRM: docker.io/espocrm/espocrm:9.3.8 (Apache variant, amd64).
  • MariaDB: docker.io/library/mariadb:11.4.12 (LTS, pinned patch version; separate from the EspoCRM image).
• Ports (loopback only):
  • 127.0.0.1:8093 → EspoCRM web (container port 80).
  • 127.0.0.1:8094 → MariaDB (container port 3306), for host-side DB access.
• MariaDB charset: utf8mb4, collation utf8mb4_unicode_ci (from the start, to avoid a later collation migration).
• siteUrl: http://127.0.0.1:8093.
• Admin user admin. DB name/user espocrm/espocrm. Passwords in plaintext in the scripts (private repo). Generate strong random passwords (e.g. openssl rand -base64 24) and set them as fixed variable values.

Data storage (bind mounts)

BIND_DIR="$HOME/.local/share/espocrm_pod"
DB_DATA_DIR="$BIND_DIR/mariadb"     # -> /var/lib/mysql
ESPO_DATA_DIR="$BIND_DIR/espocrm"   # -> /var/www/html  (app, data/upload, custom, config.php)

Mount the bind mounts plain, without :U and without :Z. Both official images run their entrypoint as root and chown their own data directories to the in-container service user before dropping privileges: MariaDB chowns /var/lib/mysql to mysql, EspoCRM chowns its writable resources (data, custom, client/custom, install/config.php) to www-data. In rootless Podman the container root maps to host user mkt and holds CAP_CHOWN inside the user namespace, so those chowns succeed on the bind-mounted host directories. No SELinux on Debian, so no :Z. This matches the other rootless pods on this host.

espocrm_ctr and espocrm_daemon_ctr share the same ESPO_DATA_DIR (both mount /var/www/html).

Container configuration

mariadb_ctr (start first)

Env variables:

MARIADB_ROOT_PASSWORD=<random>
MARIADB_DATABASE=espocrm
MARIADB_USER=espocrm
MARIADB_PASSWORD=<random>

Image arguments (utf8mb4) after the image name:

--character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci

espocrm_ctr (web, start after the DB)

Env variables:

ESPOCRM_DATABASE_PLATFORM=Mysql
ESPOCRM_DATABASE_HOST=127.0.0.1
ESPOCRM_DATABASE_PORT=3306
ESPOCRM_DATABASE_NAME=espocrm
ESPOCRM_DATABASE_USER=espocrm
ESPOCRM_DATABASE_PASSWORD=<random, identical to MARIADB_PASSWORD>
ESPOCRM_ADMIN_USERNAME=admin
ESPOCRM_ADMIN_PASSWORD=<random>
ESPOCRM_SITE_URL=http://127.0.0.1:8093
ESPOCRM_CONFIG_USE_WEB_SOCKET=false

Note: containers in a pod share the network namespace, so the DB is reachable at 127.0.0.1:3306 (not via the host port 8094). Use 127.0.0.1 instead of localhost to force TCP rather than a socket.

espocrm_daemon_ctr (scheduler, start last)

• Same image docker.io/espocrm/espocrm:9.3.8.
• Start with --entrypoint docker-daemon.sh (cron/scheduler loop).
• Mounts the same ESPO_DATA_DIR at /var/www/html.
• Reads its configuration from the data/config.php written by espocrm_ctr during install, so start it after the web container.

Script 1: create_pod_espocrm.sh (create plus autostart)

Flow:

1. Env-var block (see above) including the pinned images, ports, NET_OPTS, BIND_DIR, USER_SYSTEMD_DIR="$HOME/.config/systemd/user", and the plaintext passwords.
2. Create directories: mkdir -p "$DB_DATA_DIR" "$ESPO_DATA_DIR" "$USER_SYSTEMD_DIR".
3. Create the pod (guarded with if ! podman pod exists):

   podman pod create -n "$POD_NAME" --network "$NET_OPTS" \
     -p 127.0.0.1:8093:80 \
     -p 127.0.0.1:8094:3306
   

4. Start mariadb_ctr (podman rm -f first for idempotency), with env, -v "$DB_DATA_DIR":/var/lib/mysql, then the utf8mb4 image arguments.
5. Wait for the DB to be ready:

   for i in $(seq 1 60); do
     podman exec "$DB_CTR" mariadb-admin ping --silent >/dev/null 2>&1 && break
     sleep 2
   done
   

6. Start espocrm_ctr (podman rm -f first), with env, -v "$ESPO_DATA_DIR":/var/www/html.
7. Wait for EspoCRM install/response (HTTP 200/302 on http://127.0.0.1:8093/, max ~3 min).
8. Start espocrm_daemon_ctr (podman rm -f first), with --entrypoint docker-daemon.sh, -v "$ESPO_DATA_DIR":/var/www/html.
9. Generate systemd units: cd "$USER_SYSTEMD_DIR"; podman generate systemd --files --new --name "$POD_NAME" (produces pod-espocrm_pod.service plus container-mariadb_ctr.service, container-espocrm_ctr.service, container-espocrm_daemon_ctr.service).
10. Enforce start order (like the readiness injection in create_pod_traefik.sh): insert an ExecStartPre wait loop into container-espocrm_ctr.service and container-espocrm_daemon_ctr.service that waits for the dependency it needs (web waits for DB port 127.0.0.1:8094; daemon waits for web port 127.0.0.1:8093). Insert via awk, as in the reference script.
11. Stop and remove the live pod: podman pod stop --time 15 "$POD_NAME"; podman pod rm -f --ignore "$POD_NAME".
12. Enable the services:

    systemctl --user daemon-reload
    systemctl --user enable --now pod-${POD_NAME}.service
    systemctl --user enable --now container-mariadb_ctr.service
    systemctl --user enable --now container-espocrm_ctr.service
    systemctl --user enable --now container-espocrm_daemon_ctr.service
    

13. Print closing hints (status and log commands, as in the reference script).

Script 2: stop_pod_espocrm.sh

• Stops the systemd-managed instance: systemctl --user stop container-espocrm_daemon_ctr.service container-espocrm_ctr.service container-mariadb_ctr.service pod-${POD_NAME}.service (in this order), with echo status messages.
• Do not disable (autostart stays in place), only stop.

Script 3: reset_pod_espocrm.sh (dangerous — deletes all data)

• Extra safety prompt: only proceed after the exact confirmation phrase is entered, e.g.:

  read -r -p "WARNING: this deletes the pod, containers, and ALL data under $BIND_DIR. To confirm, type 'RESET espocrm_pod': " C
  [ "$C" = "RESET espocrm_pod" ] || { echo "Aborted."; exit 1; }
  

• Then: systemctl --user disable --now for the pod and all three containers; podman pod rm -f --ignore "$POD_NAME"; delete the generated unit files in $USER_SYSTEMD_DIR; systemctl --user daemon-reload; finally rm -rf "$BIND_DIR" (data gone).
• Print a hint that create_pod_espocrm.sh must be run again afterwards.

Script 4: backup_espocrm.sh (no timer/cron)

• Backup target BAK_DIR="$HOME/bak" (mkdir -p at the start).
• Timestamp TS=$(date +%Y%m%d-%H%M%S).
• DB dump via podman exec (so the backup script needs no password; it uses the container's own env):

  podman exec "$DB_CTR" sh -c 'exec mariadb-dump --single-transaction --routines --triggers -uroot -p"$MARIADB_ROOT_PASSWORD" espocrm' | gzip > "$BAK_DIR/espocrm-db-$TS.sql.gz"
  

  If $MARIADB_ROOT_PASSWORD is not available in the exec session, alternatively go host-side via the port: mariadb-dump -h127.0.0.1 -P8094 -uroot -p<pw> ... (password as a plaintext variable here too, same repo model). That is what port 8094 is for.
• File backup of the EspoCRM data (contains config.php with the crypt/passwordSalt key, data/upload, custom):

  tar -czf "$BAK_DIR/espocrm-files-$TS.tar.gz" -C "$ESPO_DATA_DIR" .
  

• Closing message with the created file paths.
• No timer, no cron job (manual invocation).

Sources for verifying env variable names and entrypoints

• Official image and tags: https://hub.docker.com/r/espocrm/espocrm
• Official Docker build repo (env variables, docker-daemon.sh): https://github.com/espocrm/espocrm-docker