223 lines
4.1 KiB
Markdown
223 lines
4.1 KiB
Markdown
# Docker Setup Guide
|
|
|
|
This guide explains how to build and run FurryPlace using Docker.
|
|
|
|
## Quick Start
|
|
|
|
### Prerequisites
|
|
- Docker Engine 20.10+
|
|
- Docker Compose 2.0+
|
|
|
|
### Basic Usage
|
|
|
|
1. **Build and start all services:**
|
|
```bash
|
|
docker-compose up -d
|
|
```
|
|
|
|
2. **View logs:**
|
|
```bash
|
|
docker-compose logs -f app
|
|
```
|
|
|
|
3. **Stop services:**
|
|
```bash
|
|
docker-compose down
|
|
```
|
|
|
|
4. **Stop and remove volumes (deletes database):**
|
|
```bash
|
|
docker-compose down -v
|
|
```
|
|
|
|
## Configuration
|
|
|
|
### Environment Variables
|
|
|
|
The easiest way to configure the application is to copy `.env.docker` to `.env`:
|
|
|
|
```bash
|
|
cp .env.docker .env
|
|
```
|
|
|
|
Then edit `.env` to customize:
|
|
|
|
- `PORT` - Application port (default: 3000)
|
|
- `MYSQL_*` - Database configuration
|
|
- `JWT_SECRET` - **IMPORTANT:** Change this in production!
|
|
|
|
### Production Deployment
|
|
|
|
For production, you should:
|
|
|
|
1. **Change the JWT secret:**
|
|
```env
|
|
JWT_SECRET="your-secure-random-secret-here"
|
|
```
|
|
|
|
2. **Change database passwords:**
|
|
```env
|
|
MYSQL_ROOT_PASSWORD="secure-root-password"
|
|
MYSQL_PASSWORD="secure-app-password"
|
|
```
|
|
|
|
3. **Use a reverse proxy (nginx/traefik) for SSL/HTTPS**
|
|
|
|
4. **Set up regular database backups**
|
|
|
|
## Docker Commands
|
|
|
|
### Building
|
|
|
|
```bash
|
|
# Build the application image
|
|
docker-compose build
|
|
|
|
# Build without cache
|
|
docker-compose build --no-cache
|
|
```
|
|
|
|
#### Using the precompiled frontend
|
|
|
|
If you want to serve the legacy bundle in `frontend-backup/` instead of rebuilding `frontend-src`, set the build argument while building the image:
|
|
|
|
```bash
|
|
USE_FRONTEND_BACKUP=true docker-compose build
|
|
```
|
|
|
|
With `USE_FRONTEND_BACKUP=true` the Dockerfile skips the frontend build step and copies the existing `frontend-backup/` files into `/app/frontend` inside the image.
|
|
|
|
### Running
|
|
|
|
```bash
|
|
# Start in foreground
|
|
docker-compose up
|
|
|
|
# Start in background
|
|
docker-compose up -d
|
|
|
|
# Start only specific services
|
|
docker-compose up -d mysql
|
|
```
|
|
|
|
### Monitoring
|
|
|
|
```bash
|
|
# View logs
|
|
docker-compose logs -f
|
|
|
|
# View app logs only
|
|
docker-compose logs -f app
|
|
|
|
# Check service status
|
|
docker-compose ps
|
|
```
|
|
|
|
### Database Management
|
|
|
|
```bash
|
|
# Access MySQL shell
|
|
docker-compose exec mysql mysql -u FurryPlace -p
|
|
|
|
# Run migrations
|
|
docker-compose exec app pnpm db:push
|
|
|
|
# Seed database
|
|
docker-compose exec app pnpm seed
|
|
|
|
# Backup database
|
|
docker-compose exec mysql mysqldump -u FurryPlace -pFurryPlacepassword FurryPlace > backup.sql
|
|
|
|
# Restore database
|
|
docker-compose exec -T mysql mysql -u FurryPlace -pFurryPlacepassword FurryPlace < backup.sql
|
|
```
|
|
|
|
### Maintenance
|
|
|
|
```bash
|
|
# Restart services
|
|
docker-compose restart
|
|
|
|
# Restart specific service
|
|
docker-compose restart app
|
|
|
|
# View resource usage
|
|
docker stats FurryPlace-app FurryPlace-mysql
|
|
|
|
# Clean up unused images
|
|
docker image prune
|
|
```
|
|
|
|
## Standalone Docker Build
|
|
|
|
If you prefer to build without docker-compose:
|
|
|
|
```bash
|
|
# Build image
|
|
docker build -t FurryPlace:latest .
|
|
|
|
# Run container (requires existing MySQL)
|
|
docker run -d \
|
|
--name FurryPlace \
|
|
-p 3000:3000 \
|
|
-e DATABASE_URL="mysql://user:pass@host:3306/FurryPlace" \
|
|
-e JWT_SECRET="your-secret" \
|
|
FurryPlace:latest
|
|
```
|
|
|
|
## Development with Docker
|
|
|
|
For development, you may want to mount your source code:
|
|
|
|
```bash
|
|
docker-compose -f docker-compose.dev.yml up
|
|
```
|
|
|
|
Or use the regular local development setup:
|
|
```bash
|
|
pnpm install
|
|
pnpm dev
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Database connection fails
|
|
|
|
Wait a few seconds for MySQL to initialize on first run. Check logs:
|
|
```bash
|
|
docker-compose logs mysql
|
|
```
|
|
|
|
### Port already in use
|
|
|
|
Change the port in `.env`:
|
|
```env
|
|
PORT=3001
|
|
```
|
|
|
|
### Permission issues
|
|
|
|
On Linux, you may need to adjust file permissions:
|
|
```bash
|
|
sudo chown -R $(id -u):$(id -g) .
|
|
```
|
|
|
|
### Clear everything and restart
|
|
|
|
```bash
|
|
docker-compose down -v
|
|
docker-compose up -d --build
|
|
```
|
|
|
|
## Architecture
|
|
|
|
The Docker setup consists of:
|
|
|
|
- **FurryPlace-app**: Node.js application container running the backend
|
|
- **FurryPlace-mysql**: MySQL 8.0 database container
|
|
- **mysql-data**: Persistent volume for database storage
|
|
- **FurryPlace-network**: Bridge network for container communication
|
|
|
|
The application automatically runs database migrations on startup.
|
|
|