ampache/PLAN.md

ampache migration plan

Service intent

Self-hosted music streaming server. Single Alpine-based Docker image bundling Apache (httpd) + PHP-FPM (php84) + MariaDB-server + the Ampache web app at /usr/local/share/ampache. Apache serves the app's public/ subfolder (the canonical Ampache web root since v5+). Container exposes :80; first run takes the user to install.php which provisions the database and creates an admin account. Volumes: /config (user-editable settings: ampache config, httpd conf snippets, php-fpm pool, my.cnf, secure/auth) and /data (mariadb datadir, logs, uploaded media library if mounted there).

Service stack

• Web server: apache2 (Alpine) -> /usr/sbin/httpd, main config /etc/apache2/httpd.conf, vhost include in /etc/apache2/conf.d/*.conf. Uses event MPM, mod_rewrite + AllowOverride All for the Ampache .htaccess.
• App runtime: php84-fpm (Alpine) -> /usr/sbin/php-fpm84, conf /etc/php84/php-fpm.conf + pool /etc/php84/php-fpm.d/www.conf. Apache talks to it via proxy_fcgi over a unix socket /run/php-fpm/php-fpm.sock (no exposed TCP).
• Database: mariadb + mariadb-client (Alpine) -> /usr/bin/mariadbd, datadir /data/db/mariadb, socket /run/mysqld/mysqld.sock. Started by a separate 09-mariadb.sh so it's up before ampache is rendered.
• Application: Ampache 7.9.3 (ampache-7.9.3_all_php8.4.zip from upstream GitHub releases — pre-built, vendor/ + node_modules/ already populated, no composer/npm needed at build time). Installed at /usr/local/share/ampache; Apache DocumentRoot is /usr/local/share/ampache/public.

Packages (PACK_LIST / ENV_PACKAGES)

Trimmed from the original kitchen-sink list in the existing Dockerfile. Each package is on pkgs.alpinelinux.org (verified for the edge branch).

System glue:

• bash, tini, curl, wget, unzip, tzdata, ca-certificates, pwgen — entrypoint, fetching/extracting the ampache zip, password generation.
• tar, gzip — archive handling.

Apache:

• apache2, apache2-ctl, apache2-utils — server binary, control script, htpasswd/etc.
• apache2-ssl — mod_ssl (TLS support; off by default but available).
• apache2-proxy — mod_proxy + mod_proxy_fcgi (required to forward PHP requests to php-fpm).
• apache2-http2 — http/2 support.
• apache2-brotli — mod_brotli compression.
• apache2-icons, apache2-error — icons + multilingual error pages.

(Dropped from prior list: apache2-lua apache2-ldap apache2-webdav apache2-mod-wsgi apache-mod-fcgid apache2-proxy-html — none are needed for ampache and apache2-proxy is the canonical fcgi backend, not mod_fcgid.)

PHP 8.4 — only the modules Ampache actually requires per upstream docs (PDO, PDO_MYSQL, hash, session, intl, json, curl, simplexml + optional gd, ldap, zip), plus FPM and the bare runtime:

• php84 php84-fpm php84-common php84-ctype php84-pdo php84-pdo_mysql php84-mysqli php84-mysqlnd php84-session php84-intl php84-curl php84-simplexml php84-xml php84-xmlreader php84-xmlwriter php84-dom php84-mbstring php84-iconv php84-tokenizer php84-fileinfo php84-openssl php84-phar php84-gd php84-zip php84-bz2 php84-gmp php84-exif php84-opcache php84-pecl-redis

(Dropped from prior list: dba, dev, doc, embed, enchant, ffi, ftp, gettext, imap, ldap (kept off — not needed by ampache out-of-box), litespeed, odbc, pcntl, pdo_dblib, pdo_odbc, pdo_pgsql, pdo_sqlite, pear, pgsql, phpdbg, posix, pspell, shmop, snmp, soap, sockets, sodium, sqlite3, sysvmsg, sysvsem, sysvshm, tidy, xsl, pecl-memcached, pecl-mcrypt, pecl-mongodb, calendar, cgi, bcmath. Kept what either a stock Ampache install touches or is part of ampache's bundled vendor extensions. composer is dropped — we use the prebuilt zip, no install step needed.)

MariaDB:

• mariadb — server (/usr/bin/mariadbd).
• mariadb-client — mariadb CLI client used by the post-execute initdb step.
• mariadb-server-utils — mysql_install_db, mariadb-admin, mariadb-secure-installation.

Configs to ship in rootfs/tmp/etc/

Wipe-and-replace at build time (per template §4). All paths under rootfs/tmp/etc/.

• apache2/httpd.conf — minimal Alpine apache main config: load only the modules we need (mpm_event, mime, dir, alias, authz_core, authz_host, autoindex, deflate, brotli, expires, headers, log_config, mime_magic, negotiation, proxy, proxy_fcgi, rewrite, setenvif, ssl, status, unixd, http2). User/Group apache:apache. ServerRoot /var/www. Logs to /data/logs/apache2/{access,error}.log. PidFile /run/apache2/httpd.pid. ErrorLog/LogLevel sensible defaults. Final line: IncludeOptional /etc/apache2/conf.d/*.conf and IncludeOptional /config/apache2/vhosts.d/*.conf (optional, so empty dir doesn't crash).
• apache2/conf.d/ampache.conf — vhost: <VirtualHost *:80> with DocumentRoot /usr/local/share/ampache/public, <Directory> block (Options FollowSymLinks, AllowOverride All, Require all granted), ProxyPassMatch ^/(.+\.php(/.*)?)$ unix:/run/php-fpm/php-fpm.sock|fcgi://localhost/usr/local/share/ampache/public/$1, DirectoryIndex index.php index.html. Sets SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1 (per upstream Apache vhost, needed for ampache API auth headers). ErrorLog/CustomLog under /data/logs/apache2/.
• apache2/conf.d/mpm.conf — switch to mpm_event explicitly + sane worker tunings.
• php84/php.ini — production-tuned: memory_limit = 512M, upload_max_filesize = 256M, post_max_size = 256M, max_execution_time = 300, date.timezone = ${TZ}, expose_php = Off, cgi.fix_pathinfo = 0, opcache.enable = 1, opcache.memory_consumption = 256, opcache.max_accelerated_files = 20000, session.save_path = /tmp/php-sessions.
• php84/php-fpm.conf — global: pid = /run/php-fpm/php-fpm.pid, error_log = /data/logs/php-fpm/error.log, daemonize = no (we run under our own supervisor), include=/etc/php84/php-fpm.d/*.conf.
• php84/php-fpm.d/www.conf — pool [www], user = apache, group = apache, listen = /run/php-fpm/php-fpm.sock, listen.owner = apache, listen.group = apache, listen.mode = 0660, pm = dynamic, pm.max_children = 20, pm.start_servers = 4, pm.min_spare_servers = 2, pm.max_spare_servers = 8, pm.max_requests = 500, clear_env = no.
• my.cnf.d/mariadb-server.cnf — server config: [mysqld] with datadir = /data/db/mariadb, socket = /run/mysqld/mysqld.sock, bind-address = 127.0.0.1 (DB only reachable inside container), port = 3306, character-set-server = utf8mb4, collation-server = utf8mb4_unicode_ci, max_allowed_packet = 64M, innodb_buffer_pool_size = 256M, log_error = /data/logs/mariadb/mariadb.err.log, pid-file = /run/mysqld/mariadb.pid. [client] socket = /run/mysqld/mysqld.sock. [mysqld_safe] matching log path.
• ampache/ampache.cfg.php.dist — empty placeholder (or a copy of the ampache-shipped dist file). Real ampache.cfg.php is generated by install.php on first web visit.

/config// layout (user-editable)

The framework's __initialize_system_etc symlinks every file under /config/<svc>/ back to its /etc/<svc>/ peer. So our /config/ seed (via template-files/config/) mirrors /etc/ with the same paths:

• /config/apache2/httpd.conf -> symlinked to /etc/apache2/httpd.conf
• /config/apache2/conf.d/ampache.conf -> symlinked to /etc/apache2/conf.d/ampache.conf
• /config/apache2/conf.d/mpm.conf -> symlinked to /etc/apache2/conf.d/mpm.conf
• /config/apache2/vhosts.d/*.conf -> picked up by the IncludeOptional line for user-supplied vhosts
• /config/php84/php.ini -> /etc/php84/php.ini
• /config/php84/php-fpm.conf -> /etc/php84/php-fpm.conf
• /config/php84/php-fpm.d/www.conf -> /etc/php84/php-fpm.d/www.conf
• /config/my.cnf.d/mariadb-server.cnf -> /etc/my.cnf.d/mariadb-server.cnf
• /config/ampache/ampache.cfg.php -> bind-mounted into /usr/local/share/ampache/config/ampache.cfg.php (created post-install by install.php; we symlink the live file out to /config/ampache/ after install completes so it survives container recreation).
• /config/secure/auth/{root,user}/{ampache,mariadb}_{name,pass} -> generated/used by the framework
• /config/env/{ampache,mariadb}.sh -> per-service env overrides

ADDITIONAL_CONFIG_DIRS for ampache will be /config/apache2 /config/php84 /config/my.cnf.d /config/ampache so each one runs through __initialize_system_etc.

init.d/99-ampache.sh (and 09-mariadb.sh)

Two init.d scripts. MariaDB starts first (09-), Apache+PHP-FPM start under ampache (99-).

rootfs/usr/local/etc/docker/init.d/09-mariadb.sh — copy of mariadb repo's 09-mariadb.sh with these knobs:

• SERVICE_NAME="mariadb", EXEC_CMD_BIN='mariadbd', EXEC_CMD_ARGS='--user=$SERVICE_USER --datadir=$DATABASE_DIR --socket=/run/mysqld/mysqld.sock'
• SERVICE_USER="mysql", SERVICE_GROUP="mysql"
• IS_DATABASE_SERVICE="yes", DATABASE_SERVICE_TYPE="mariadb"
• __run_pre_execute_checks_local: bootstrap datadir if missing (mysql_install_db --datadir=$DATABASE_DIR --user=mysql).
• __post_execute_local: when first run, create the ampache database + ampache user + grant; write password to /config/secure/auth/user/ampache_db_pass.

rootfs/usr/local/etc/docker/init.d/99-ampache.sh — based on nginx's 99-nginx.sh structure:

• SERVICE_NAME="ampache", SERVICE_USER="apache", SERVICE_GROUP="apache"
• EXEC_CMD_BIN='httpd', EXEC_CMD_ARGS='-D FOREGROUND -f /etc/apache2/httpd.conf'
• EXEC_PRE_SCRIPT='/usr/sbin/php-fpm84' — start php-fpm as the pre-script (it reads /etc/php84/php-fpm.conf with daemonize=no but we run it before httpd; the framework's EXEC_PRE_SCRIPT pattern handles this).
• IS_WEB_SERVER="yes", USES_DATABASE_SERVICE="yes", DATABASE_SERVICE_TYPE="mariadb"
• WWW_ROOT_DIR="/usr/local/share/ampache/public", ETC_DIR="/etc/apache2", CONF_DIR="/config/apache2"
• ADDITIONAL_CONFIG_DIRS="/config/php84 /config/my.cnf.d /config/ampache"
• SERVICE_PORT="80"
• __execute_prerun_local: ensure runtime dirs (/run/apache2, /run/php-fpm, /run/mysqld, /tmp/php-sessions, /data/logs/{apache2,php-fpm,mariadb,ampache}) exist with right ownership; chown /usr/local/share/ampache/{config,channel,rest,play} to apache:apache for the install.php writes; symlink /usr/local/share/ampache/config/ampache.cfg.php -> /config/ampache/ampache.cfg.php if not present.
• __pre_execute_local: wait for mariadb socket to appear (/run/mysqld/mysqld.sock) up to 30s before starting apache.
• __update_conf_files_local: replace REPLACE_TZ token in /etc/php84/php.ini with $TZ. (No tokens in apache or my.cnf — paths are baked in.)

05-custom.sh additions

Replace the current placeholder content (which only mkdirs and creates an empty webapp dir) with:

1. Wipe distro-default /etc/{apache2,php84,my.cnf.d}/* (drop conf.d/{default,info,languages,mpm,userdir}.conf, ssl.conf etc.) so only our shipped files remain after cp -Rf /tmp/etc/....

   for d in apache2 php84 my.cnf.d; do
     [ -d /tmp/etc/$d ] || continue
     rm -Rf /etc/$d/*
     cp -Rf /tmp/etc/$d/. /etc/$d/
   done
   

2. Fetch + install Ampache 7.9.3 prebuilt zip:

   AMPACHE_VERSION="7.9.3"
   AMPACHE_URL="https://github.com/ampache/ampache/releases/download/${AMPACHE_VERSION}/ampache-${AMPACHE_VERSION}_all_php8.4.zip"
   mkdir -p /usr/local/share/ampache
   cd /tmp
   wget -q -O /tmp/ampache.zip "$AMPACHE_URL"
   unzip -q /tmp/ampache.zip -d /usr/local/share/ampache
   rm -f /tmp/ampache.zip
   chown -R apache:apache /usr/local/share/ampache
   # ensure config dir exists for install.php to drop ampache.cfg.php
   mkdir -p /usr/local/share/ampache/config
   chown apache:apache /usr/local/share/ampache/config
   

3. Create runtime dirs needed by apache/php-fpm/mariadb so the first start doesn't trip on missing parents:

   mkdir -p /run/apache2 /run/php-fpm /run/mysqld /var/log/apache2 /tmp/php-sessions
   

4. Stage seed template-files/config/ampache/ with an empty .gitkeep so __initialize_config_dir creates /config/ampache/ on first run (the real ampache.cfg.php is written by install.php).

04-users.sh additions

The mariadb Alpine package creates the mysql user automatically; the apache2 package creates apache. So 04-users.sh stays mostly empty — but add a defensive addgroup -S apache 2>/dev/null; adduser -S -G apache -h /var/www -s /sbin/nologin apache 2>/dev/null block in case package ordering doesn't guarantee them.

02-packages.sh additions

Empty (no per-package compile or pip step needed; the prebuilt ampache zip has all PHP deps inside vendor/).

Dockerfile changes

• Update BUILD_DATE to 202605091200 (today, 2026-05-09 12:00).
• Replace PACK_LIST with the trimmed list above.
• Keep everything else (multi-stage, scratch final, ARGs, ENVs, volumes, healthcheck).
• No structural changes — the template's RUN steps already invoke 00–07 setup scripts in order.

.env.scripts changes

• Sync ENV_PACKAGES to match the new PACK_LIST (single space separated, no double spaces).
• Leave SERVICE_PORT="80", EXPOSE_PORTS="", PHP_VERSION="php84".

README updates

Document the first-run workflow: visit http://localhost:8080/ → ampache installer → fill in DB host 127.0.0.1, user ampache, password from /config/secure/auth/user/ampache_db_pass (or read from docker exec), DB name ampache (already created by post-execute), web admin → enter desired admin user/email/pass → done. Note the volumes (/config, /data) and the music library mount pattern (-v /path/to/music:/media:ro).

Verification (success criteria)

1. cd /root/Projects/github/casjaysdevdocker/ampache && rm -f .build_failed && buildx run Dockerfile succeeds for both linux/amd64 and linux/arm64. Single retry permitted on transient network errors.
2. docker run -d --rm --name test-ampache -p 18080:80 docker.io/casjaysdevdocker/ampache:latest boots; after ~60s, docker logs test-ampache | tail -50 shows no fatal errors and shows mariadb + php-fpm + httpd all started (look for "ready for connections", "fpm is running", "Apache/2... configured -- resuming normal operations").
3. curl -fsS -o /dev/null -w '%{http_code}' http://localhost:18080/ returns 200 or 302 (the install.php redirect).
4. docker exec test-ampache ls /config/ampache/ /config/apache2/ /config/php84/ /data/db/mariadb/ /usr/local/share/ampache/public/index.php — every path exists.
5. docker exec test-ampache mariadb -u root -e 'SHOW DATABASES;' lists ampache.
6. docker stop test-ampache.

Rollback

If anything in this PLAN.md proves wrong, the existing files are recoverable from git (git checkout -- rootfs/). New files (init.d, tmp/etc) can be removed cleanly because they didn't exist before.