Document Environment Variable Requirements for Service Database Backups

[Cinzya]

Summary

The current backup documentation does not mention the specific environment variable requirements for Service Databases (databases deployed as Docker Compose services). This causes confusion when backups fail due to missing or incorrectly named environment variables.

Problem

Service Database backups can fail silently or with unclear error messages when the required environment variables are not present in the database containers. Users are not informed about these requirements in the documentation.

Analysis

Based on the DatabaseBackupJob.php implementation, Coolify detects database credentials by executing commands like docker exec <container> env | grep <DB_PREFIX>_ and expects specific environment variable names:

Required Environment Variables by Database Type

PostgreSQL Services

• Required: POSTGRES_PASSWORD=<password>
• Optional: POSTGRES_USER=<username> (defaults to postgres)
• Optional: POSTGRES_DB=<database_name> (defaults to username)
• Detection: docker exec <container> env | grep POSTGRES_

MySQL Services

• Required: MYSQL_ROOT_PASSWORD=<password>
• Optional: MYSQL_DATABASE=<database_name> (throws exception if missing)
• Detection: docker exec <container> env | grep MYSQL_

MariaDB Services

• Primary: MARIADB_ROOT_PASSWORD=<password>
• Fallback: MYSQL_ROOT_PASSWORD=<password>
• Database: MARIADB_DATABASE=<database_name> or MYSQL_DATABASE=<database_name>
• Detection: docker exec <container> env

MongoDB Services

• Required: MONGO_INITDB_ROOT_USERNAME=<username>
• Required: MONGO_INITDB_ROOT_PASSWORD=<password>
• Detection: docker exec <container> env | grep MONGO_INITDB_

Prerequisites

1. Container must be in "running" status
2. Container naming: {database_name}-{service_uuid}
3. Coolify server must have docker exec access
4. Environment variable names are case-sensitive and must match exactly

Proposed Solution

Add a new section to /docs/databases/backups.md titled "Environment Variable Requirements" that documents:

1. The difference between Service Databases and Standalone databases
2. Required environment variables for each database type
3. Prerequisites for successful backup
4. Troubleshooting steps for backup failures
5. Commands to manually verify environment variables

Impact

This documentation will help users:

• Understand why their backups might be failing
• Configure their Service Databases correctly
• Troubleshoot backup issues more effectively
• Avoid silent backup failures

Files to Update

• docs/databases/backups.md - Add environment variable requirements section