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**
   ```bash
   cd /path/to/your/project
   ```

2. **Install PostgreSQL dependencies**
   ```bash
   cd server
   npm install pg
   cd ..
   ```

3. **Generate secure environment variables**
   ```bash
   # 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)
   ```bash
   cp docker-compose.env .env
   # Edit .env file with your generated secrets
   ```

5. **Start the services**
   ```bash
   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:

```bash
./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**
   ```bash
   cp docker-compose.env .env
   ```

2. **Edit the .env file**
   ```bash
   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

```bash
# 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
```javascript
// 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