linkforty/DOCKER.md

# Docker Deployment Guide

This guide covers deploying LinkForty using Docker and Docker Compose.

## Quick Start

### Using Docker Compose (Recommended)

1. **Download the docker-compose.yml file:**
   ```bash
   curl -O https://raw.githubusercontent.com/linkforty/core/main/docker-compose.yml
   ```

2. **Create a `.env` file:**
   ```bash
   # Download the example
   curl -O https://raw.githubusercontent.com/linkforty/core/main/.env.example
   mv .env.example .env

   # Edit with your settings
   nano .env
   ```

3. **Start LinkForty:**
   ```bash
   docker-compose up -d
   ```

4. **Access your instance:**
   - API: http://localhost:3000
   - Health check: http://localhost:3000/health

### Using Docker CLI

```bash
# Pull the latest image
docker pull linkforty/core:latest

# Run with required services
docker run -d \
  --name linkforty \
  -p 3000:3000 \
  -e DATABASE_URL=postgresql://user:pass@host:5432/db \
  -e REDIS_URL=redis://host:6379 \
  linkforty/core:latest
```

## Configuration

### Environment Variables

| Variable       | Required | Default      | Description                           |
|----------------|----------|--------------|---------------------------------------|
| `DATABASE_URL` | Yes      | -            | PostgreSQL connection string          |
| `REDIS_URL`    | No       | -            | Redis connection string (recommended) |
| `PORT`         | No       | `3000`       | Server port                           |
| `NODE_ENV`     | No       | `production` | Environment mode                      |
| `JWT_SECRET`   | No       | -            | JWT signing secret                    |

See [.env.example](.env.example) for complete configuration options.

### Docker Compose Configuration

The `docker-compose.yml` file includes:
- **LinkForty API** - Main application server
- **PostgreSQL** - Database for persistent storage
- **Redis** - Caching layer for performance

#### Customizing Ports

Edit your `.env` file:
```env
LINKFORTY_PORT=8080  # Change API port
POSTGRES_PORT=5433   # Change Postgres port
REDIS_PORT=6380      # Change Redis port
```

#### Using Your Own Database

If you have an existing PostgreSQL or Redis instance:

```yaml
# docker-compose.yml
services:
  linkforty:
    image: linkforty/core:latest
    environment:
      DATABASE_URL: postgresql://user:pass@your-db-host:5432/linkforty
      REDIS_URL: redis://your-redis-host:6379
    # Remove the postgres and redis services
```

## Production Deployment

### Security Best Practices

1. **Change default passwords:**
   ```bash
   # Generate secure random password
   openssl rand -base64 32
   ```

2. **Use secrets for sensitive data:**
   ```bash
   # Create a secrets file
   echo "postgresql://user:$(openssl rand -base64 32)@postgres:5432/linkforty" > db_url.secret
   ```

   ```yaml
   # docker-compose.yml
   services:
     linkforty:
       secrets:
         - db_url
   secrets:
     db_url:
       file: ./db_url.secret
   ```

3. **Use a reverse proxy (Nginx/Traefik):**
   ```yaml
   # Add Nginx service
   services:
     nginx:
       image: nginx:alpine
       ports:
         - "80:80"
         - "443:443"
       volumes:
         - ./nginx.conf:/etc/nginx/nginx.conf:ro
         - ./ssl:/etc/nginx/ssl:ro
   ```

### Persistent Data

Volumes are automatically created for:
- `postgres_data` - Database files
- `redis_data` - Redis persistence

**Backup your data:**
```bash
# Backup PostgreSQL
docker-compose exec postgres pg_dump -U linkforty linkforty > backup.sql

# Backup volumes
docker run --rm -v linkforty_postgres_data:/data -v $(pwd):/backup alpine \
  tar czf /backup/postgres-backup.tar.gz /data
```

### Health Checks

The LinkForty container includes a built-in health check:

```bash
# Check container health
docker ps

# View health check logs
docker inspect --format='{{json .State.Health}}' linkforty | jq
```

## Versioning

### Available Tags

- `latest` - Latest stable release
- `v1.3.0` - Specific version
- `v1.3` - Latest patch of minor version
- `v1` - Latest minor of major version
- `sha-abc123` - Specific commit build

### Pinning Versions

**Recommended for production:**
```yaml
services:
  linkforty:
    image: linkforty/core:v1.3.0  # Pin to specific version
```

### Updating

```bash
# Pull latest version
docker-compose pull

# Restart with new version
docker-compose up -d

# View logs
docker-compose logs -f linkforty
```

## Troubleshooting

### Container won't start

1. **Check logs:**
   ```bash
   docker-compose logs linkforty
   ```

2. **Verify database connection:**
   ```bash
   docker-compose exec linkforty sh -c 'echo "SELECT 1" | psql $DATABASE_URL'
   ```

3. **Check health status:**
   ```bash
   docker-compose ps
   ```

### Database migration issues

Run migrations manually:
```bash
docker-compose exec linkforty tsx dist/scripts/migrate.js
```

### Port already in use

Change the port mapping in `.env`:
```env
LINKFORTY_PORT=8080
```

Or use different ports in docker-compose:
```yaml
services:
  linkforty:
    ports:
      - "8080:3000"  # External:Internal
```

## Advanced Configuration

### Multi-Architecture Support

The published images support both AMD64 and ARM64:
```bash
# Automatically pulls correct architecture
docker pull linkforty/core:latest
```

### Custom Dockerfile

If you need to customize the image:

```dockerfile
FROM linkforty/core:latest

# Add custom scripts
COPY ./custom-scripts /app/scripts

# Install additional tools
RUN apk add --no-cache curl

# Custom entrypoint
COPY ./entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]
```

### Development Mode

Build and run locally:
```bash
# Clone repository
git clone https://github.com/linkforty/core.git
cd core

# Build image
docker build -t linkforty-dev .

# Run with development settings
docker-compose -f docker-compose.yml up
```

## GitHub Actions Auto-Publishing

Images are automatically published when:
- **Tags are pushed** (e.g., `v1.3.0`) → Triggers release build
- **Main branch updated** → Updates `latest` tag
- **Pull requests** → Test build only (not published)

### Setting Up Auto-Publishing (For Maintainers)

1. Create Docker Hub access token at https://hub.docker.com/settings/security

2. Add GitHub secrets:
   - Go to repository Settings → Secrets and variables → Actions
   - Add `DOCKERHUB_USERNAME` (your Docker Hub username)
   - Add `DOCKERHUB_TOKEN` (your access token)

3. Create a new release:
   ```bash
   git tag v1.3.1
   git push origin v1.3.1
   ```

4. GitHub Actions will automatically:
   - Build the Docker image
   - Run tests
   - Push to Docker Hub
   - Create GitHub release notes

## Support

- **Issues:** https://github.com/linkforty/core/issues
- **Discussions:** https://github.com/linkforty/core/discussions
- **Documentation:** https://docs.linkforty.com

## License

MIT License - see [LICENSE](LICENSE) for details