mysql

Stack Docker para subir MariaDB com configuração local via .env.

Documentação específica de operação do MariaDB: mariadb.md

Arquivos versionados

• docker-compose.yml: stack base do banco.
• Dockerfile: imagem parametrizável para publicar no GHCR.
• .env.example: valores de exemplo para copiar para .env.
• .gitignore: impede versionamento de arquivos sensíveis e locais.

Imagem no GHCR

O repositório possui workflow em publish-ghcr.yml para buildar e publicar a imagem no GitHub Container Registry.

• Em push para main, o workflow publica ghcr.io/librecodecoop/mysql:latest e uma tag com o SHA curto do commit.
• Em execução manual, é possível informar base_image para escolher a imagem de origem, por exemplo mariadb:11.4 ou outra tag compatível, e image_tag para publicar uma tag adicional.

Exemplo de uso no .env:

MYSQL_IMAGE=ghcr.io/librecodecoop/mysql:latest

Arquivos locais

• .env: customiza imagem, credenciais, portas e paths locais.
• docker-compose.override.yml: serviços auxiliares opcionais, como PHPMyAdmin.

Subir o banco

1. Copie o arquivo de ambiente:

   cp .env.example .env

2. Ajuste os valores do .env.

3. Suba o serviço:

   docker compose up -d

4. Confira o status:

   docker compose ps

Variáveis suportadas no .env

Exemplo mínimo:

MYSQL_IMAGE=mariadb:11.4
MYSQL_CONTAINER_NAME=mysql
MYSQL_PORT=3306
MYSQL_ROOT_PASSWORD=change-me
MYSQL_DATABASE=app
MYSQL_USER=app
MYSQL_PASSWORD=change-me-too
MYSQL_DATA_DIR=./data
MYSQL_CONF_DIR=./conf.d
TZ=UTC

Troque MYSQL_IMAGE para ajustar a tag do MariaDB, por exemplo:

MYSQL_IMAGE=mariadb:11.8

Observação: valide a tag escolhida antes de atualizar em produção.

PHPMyAdmin

O PHPMyAdmin deve ficar em um docker-compose.override.yml local, não versionado.

Crie o arquivo:

cat > docker-compose.override.yml <<'EOF'
services:
  phpmyadmin:
    image: phpmyadmin:5-apache
    container_name: phpmyadmin
    restart: unless-stopped
    depends_on:
      - mysql
    environment:
      PMA_HOST: mysql
      PMA_PORT: 3306
      UPLOAD_LIMIT: 256M
      TZ: ${TZ:-UTC}
      VIRTUAL_HOST: pma.example.com
      LETSENCRYPT_HOST: pma.example.com
      LETSENCRYPT_EMAIL: infra@example.com
    networks:
      - default
      - reverse-proxy

networks:
  reverse-proxy:
    external: true
EOF

O bloco reverse-proxy serve para integrar este stack a um proxy reverso externo, por exemplo o padrão usado em ambientes baseados no repositório nginx-proxy. Se este host não usar essa topologia, remova a network extra e publique a porta manualmente.

Depois suba normalmente:

docker compose up -d

TOTP no PHPMyAdmin

1. Faça login com um usuário administrativo.
2. Abra Settings.
3. Vá em Features.
4. Ative autenticação Two-factor.
5. Cadastre o TOTP no aplicativo autenticador.
6. Salve o segredo TOTP junto das credenciais em um arquivo .kdbx.

Recomendação: no .kdbx, manter no mesmo registro a URL, usuário, senha, segredo TOTP e observações sobre o host.

Backup

Para estratégia de backup automatizado, usar este dump SQL e apontar o armazenamento/agenda central para o repositório do Duplicati da organização.

É recomendável manter sempre o mesmo nome de arquivo no dump local para ferramentas que deduplicam ou fazem incremental em cima de diferenças de arquivo.

Comando de dump:

set -a && . ./.env && set +a && docker compose exec -T mysql /usr/bin/mariadb-dump -u root --password="$MYSQL_ROOT_PASSWORD" --all-databases --add-drop-database > /root/projects/mysql/volumes/mysql/dump/dump.sql

Cron

Não coloque a senha de root diretamente no crontab. O job deve ler do .env.

Exemplo de crontab:

40 02 * * * export $(cat /root/projects/mysql/.env|grep MYSQL_ROOT_PASSWORD | xargs) && docker compose -f /root/projects/mysql/docker-compose.yml exec mysql /usr/bin/mariadb-dump -u root --password="$MYSQL_ROOT_PASSWORD" --all-databases --add-drop-database > /root/projects/mysql/volumes/mysql/dump/dump.sql

Depois, faça o backup desse dump.sql com a stack ou rotina central de Duplicati.

Atualização do MariaDB

Procedimento conservador:

1. Validar a versão atual:

   docker compose ps
   docker exec mysql mariadb --version

2. Gerar backup completo antes da mudança:

   cd /root/projects/mysql
   set -a && . ./.env && set +a && docker exec mysql /usr/bin/mariadb-dump -u root --password="$MYSQL_ROOT_PASSWORD" --all-databases > /root/projects/mysql/backup-before-upgrade.sql

3. Alterar a imagem no .env:

   MYSQL_IMAGE=mariadb:11.4

4. Conferir notas oficiais da versão de origem e destino antes do upgrade.

5. Aplicar a nova imagem:

   docker compose pull
   docker compose up -d

6. Validar logs e acesso:

   set -a && . ./.env && set +a
   docker compose logs --tail=100 mysql
   docker exec mysql mariadb -u root --password="$MYSQL_ROOT_PASSWORD" -e 'SHOW DATABASES;'

7. Se o upgrade falhar e o banco não subir corretamente, restaurar usando o dump gerado antes da mudança.

Em ambiente crítico, o ideal é testar o upgrade em cópia do volume ou ambiente de homologação antes de aplicar em produção.