pole-book/DOCKER_README.md

Strapi with PostgreSQL and Astro Client - Docker Compose Setup

This setup provides a complete Docker Compose environment for running Strapi with PostgreSQL and an Astro frontend client.

Prerequisites

• Docker
• Docker Compose

Quick Start

1. Clone and navigate to the project directory

   cd /path/to/your/project
   

2. Install PostgreSQL dependencies

   cd server
   npm install pg
   cd ..
   

3. Generate secure environment variables

   # Generate JWT secrets (you can use any secure random string generator)
   echo "JWT_SECRET=$(openssl rand -base64 32)"
   echo "ADMIN_JWT_SECRET=$(openssl rand -base64 32)"
   echo "APP_KEYS=$(openssl rand -base64 32),$(openssl rand -base64 32),$(openssl rand -base64 32),$(openssl rand -base64 32)"
   echo "API_TOKEN_SALT=$(openssl rand -base64 32)"
   echo "TRANSFER_TOKEN_SALT=$(openssl rand -base64 32)"
   

4. Create a .env file (copy from docker-compose.env and update with your generated secrets)

   cp docker-compose.env .env
   # Edit .env file with your generated secrets
   

5. Start the services

   docker-compose up -d
   

6. Access the applications

   • Strapi Admin Panel: http://localhost:1337/admin
   • Strapi API: http://localhost:1337/api
   • Astro Client: http://localhost:4321

Environment Variables Setup

Automatic Setup (Recommended)

Use the provided setup script to automatically configure environment variables:

./setup-env.sh

This script will:

• Copy docker-compose.env to .env
• Generate secure random secrets for JWT tokens and salts
• Set up all necessary environment variables

Manual Setup

If you prefer to set up environment variables manually:

1. Copy the environment template

   cp docker-compose.env .env
   

2. Edit the .env file

   nano .env  # or use your preferred editor
   

3. Update sensitive values

   • Replace all your-*-here-change-this-in-production values with secure random strings
   • Modify database credentials if needed
   • Adjust URLs and ports as required

Environment Variables Reference

The following variables are available in docker-compose.env:

Database Configuration

• DATABASE_CLIENT: Database type (postgres)
• DATABASE_HOST: Database host (postgres)
• DATABASE_PORT: Database port (5432)
• DATABASE_NAME: Database name (strapi)
• DATABASE_USERNAME: Database username (strapi)
• DATABASE_PASSWORD: Database password (strapi_password)
• DATABASE_SSL: SSL connection (false)

Strapi Configuration

• NODE_ENV: Environment (development/production)
• JWT_SECRET: JWT signing secret
• ADMIN_JWT_SECRET: Admin JWT signing secret
• APP_KEYS: Application keys (comma-separated)
• API_TOKEN_SALT: API token salt
• TRANSFER_TOKEN_SALT: Transfer token salt
• HOST: Server host (0.0.0.0)
• PORT: Server port (1337)

Client Configuration

• CLIENT_NODE_ENV: Client environment (development/production)
• STRAPI_URL: Strapi API URL (http://strapi:1337)

Security Notes

• The .env file is gitignored for security reasons
• Never commit sensitive secrets to version control
• Use different secrets for development and production
• Regularly rotate secrets in production environments

Services

Strapi Application (Backend)

• Port: 1337
• Container: strapi-app
• Database: PostgreSQL
• Purpose: Headless CMS and API

Astro Client (Frontend)

• Port: 4321
• Container: astro-client
• Purpose: Frontend application
• Backend: Connects to Strapi API

PostgreSQL Database

• Port: 5432
• Container: strapi-postgres
• Database: strapi
• Username: strapi
• Password: strapi_password

Environment Variables

The following environment variables are configured:

Strapi Configuration

• DATABASE_CLIENT: postgres
• DATABASE_HOST: postgres (Docker service name)
• DATABASE_PORT: 5432
• DATABASE_NAME: strapi
• DATABASE_USERNAME: strapi
• DATABASE_PASSWORD: strapi_password
• NODE_ENV: development

Client Configuration

• NODE_ENV: development
• STRAPI_URL: http://strapi:1337 (internal Docker network)

Volumes

• postgres_data: Persistent PostgreSQL data
• ./server/public/uploads: Strapi uploads directory
• ./server/.tmp: Strapi temporary files
• ./client/src: Astro source code (for development)
• ./client/public: Astro public assets
• ./client/astro.config.mjs: Astro configuration
• ./client/tsconfig.json: TypeScript configuration

Useful Commands

# Start all services
docker-compose up -d

# View logs for specific services
docker-compose logs -f strapi
docker-compose logs -f client
docker-compose logs -f postgres

# View all logs
docker-compose logs -f

# Stop all services
docker-compose down

# Stop and remove volumes (WARNING: This will delete all data)
docker-compose down -v

# Rebuild and start
docker-compose up -d --build

# Rebuild specific service
docker-compose up -d --build client

# Access PostgreSQL directly
docker-compose exec postgres psql -U strapi -d strapi

# Access Strapi container
docker-compose exec strapi sh

# Access Astro client container
docker-compose exec client sh

Development Workflow

Hot Reload

Both Strapi and Astro support hot reloading in development mode:

• Changes to Strapi files will automatically restart the server
• Changes to Astro files will automatically reload the browser

API Communication

The Astro client can communicate with Strapi using:

• Internal Docker network: http://strapi:1337
• External access: http://localhost:1337

Example API call from Astro

// In your Astro component or page
const response = await fetch('http://strapi:1337/api/your-content-type');
const data = await response.json();

First Time Setup

1. After starting the services, visit http://localhost:1337/admin
2. Create your first admin user
3. Configure your content types and permissions
4. Visit http://localhost:4321 to see your Astro frontend
5. Configure your Astro app to fetch data from Strapi

Production Considerations

For production deployment:

1. Change all default passwords and secrets
2. Use proper SSL certificates
3. Set NODE_ENV=production for both services
4. Configure proper backup strategies for PostgreSQL
5. Use environment-specific configuration files
6. Consider using Docker secrets for sensitive data
7. Build the Astro app for production: npm run build
8. Use a production-ready web server for the Astro build

Troubleshooting

Strapi won't start

• Check if PostgreSQL is running: docker-compose logs postgres
• Verify database connection settings
• Check if all environment variables are set correctly

Astro client won't start

• Check if Strapi is running: docker-compose logs strapi
• Verify the STRAPI_URL environment variable
• Check for port conflicts on 4321

Database connection issues

• Ensure PostgreSQL container is healthy: docker-compose ps
• Check database logs: docker-compose logs postgres
• Verify network connectivity between containers

Permission issues

• Ensure proper file permissions on mounted volumes
• Check if the Docker user has access to the project files

Network connectivity between services

• Verify all services are on the same network: docker network ls
• Check if services can reach each other using container names