feat: docker
This commit is contained in:
Valknar XXX
334
QUICKSTART.md
Normal file
334
QUICKSTART.md
Normal file
@@ -0,0 +1,334 @@
|
||||
# Quick Start Guide
|
||||
|
||||
Get sexy.pivoine.art running in under 5 minutes using pre-built Docker images.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Docker 20.10+
|
||||
- Docker Compose 2.0+ (optional)
|
||||
|
||||
## Option 1: Docker Run (Fastest)
|
||||
|
||||
### Step 1: Pull the Image
|
||||
|
||||
```bash
|
||||
docker pull ghcr.io/valknarxxx/sexy:latest
|
||||
```
|
||||
|
||||
### Step 2: Create Environment File
|
||||
|
||||
```bash
|
||||
cat > .env.production << EOF
|
||||
PUBLIC_API_URL=https://api.your-domain.com
|
||||
PUBLIC_URL=https://your-domain.com
|
||||
PUBLIC_UMAMI_ID=
|
||||
LETTERSPACE_API_URL=
|
||||
LETTERSPACE_API_KEY=
|
||||
LETTERSPACE_LIST_ID=
|
||||
EOF
|
||||
```
|
||||
|
||||
### Step 3: Run the Container
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name sexy-pivoine \
|
||||
-p 3000:3000 \
|
||||
--env-file .env.production \
|
||||
--restart unless-stopped \
|
||||
ghcr.io/valknarxxx/sexy:latest
|
||||
```
|
||||
|
||||
### Step 4: Verify
|
||||
|
||||
```bash
|
||||
# Check if running
|
||||
docker ps | grep sexy-pivoine
|
||||
|
||||
# Check logs
|
||||
docker logs -f sexy-pivoine
|
||||
|
||||
# Test the application
|
||||
curl http://localhost:3000
|
||||
```
|
||||
|
||||
Your application is now running at `http://localhost:3000` 🎉
|
||||
|
||||
## Option 2: Docker Compose (Recommended)
|
||||
|
||||
### Step 1: Download docker-compose.production.yml
|
||||
|
||||
```bash
|
||||
curl -O https://raw.githubusercontent.com/valknarxxx/sexy/main/docker-compose.production.yml
|
||||
```
|
||||
|
||||
Or if you have the repository:
|
||||
|
||||
```bash
|
||||
cd /path/to/sexy.pivoine.art
|
||||
```
|
||||
|
||||
### Step 2: Create Environment File
|
||||
|
||||
```bash
|
||||
cp .env.production.example .env.production
|
||||
nano .env.production # Edit with your values
|
||||
```
|
||||
|
||||
### Step 3: Start Services
|
||||
|
||||
```bash
|
||||
docker-compose -f docker-compose.production.yml up -d
|
||||
```
|
||||
|
||||
### Step 4: Monitor
|
||||
|
||||
```bash
|
||||
# View logs
|
||||
docker-compose -f docker-compose.production.yml logs -f
|
||||
|
||||
# Check status
|
||||
docker-compose -f docker-compose.production.yml ps
|
||||
```
|
||||
|
||||
Your application is now running at `http://localhost:3000` 🎉
|
||||
|
||||
## Accessing Private Images
|
||||
|
||||
If the image is in a private registry:
|
||||
|
||||
### Step 1: Create GitHub Personal Access Token
|
||||
|
||||
1. Go to https://github.com/settings/tokens
|
||||
2. Click "Generate new token (classic)"
|
||||
3. Select scope: `read:packages`
|
||||
4. Generate and copy the token
|
||||
|
||||
### Step 2: Login to GitHub Container Registry
|
||||
|
||||
```bash
|
||||
echo YOUR_GITHUB_TOKEN | docker login ghcr.io -u YOUR_GITHUB_USERNAME --password-stdin
|
||||
```
|
||||
|
||||
### Step 3: Pull and Run
|
||||
|
||||
Now you can pull private images:
|
||||
|
||||
```bash
|
||||
docker pull ghcr.io/valknarxxx/sexy:latest
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
### Required
|
||||
|
||||
| Variable | Description | Example |
|
||||
|----------|-------------|---------|
|
||||
| `PUBLIC_API_URL` | Directus API endpoint | `https://api.pivoine.art` |
|
||||
| `PUBLIC_URL` | Frontend URL | `https://sexy.pivoine.art` |
|
||||
|
||||
### Optional
|
||||
|
||||
| Variable | Description | Example |
|
||||
|----------|-------------|---------|
|
||||
| `PUBLIC_UMAMI_ID` | Analytics tracking ID | `abc-123-def` |
|
||||
| `LETTERSPACE_API_URL` | Newsletter API | `https://api.letterspace.com/v1` |
|
||||
| `LETTERSPACE_API_KEY` | Newsletter API key | `sk_live_...` |
|
||||
| `LETTERSPACE_LIST_ID` | Mailing list ID | `list_abc123` |
|
||||
|
||||
## Common Commands
|
||||
|
||||
### View Logs
|
||||
|
||||
```bash
|
||||
# Follow logs (Docker Run)
|
||||
docker logs -f sexy-pivoine
|
||||
|
||||
# Follow logs (Docker Compose)
|
||||
docker-compose -f docker-compose.production.yml logs -f
|
||||
```
|
||||
|
||||
### Restart Container
|
||||
|
||||
```bash
|
||||
# Docker Run
|
||||
docker restart sexy-pivoine
|
||||
|
||||
# Docker Compose
|
||||
docker-compose -f docker-compose.production.yml restart
|
||||
```
|
||||
|
||||
### Stop Container
|
||||
|
||||
```bash
|
||||
# Docker Run
|
||||
docker stop sexy-pivoine
|
||||
|
||||
# Docker Compose
|
||||
docker-compose -f docker-compose.production.yml down
|
||||
```
|
||||
|
||||
### Update to Latest Version
|
||||
|
||||
```bash
|
||||
# Docker Run
|
||||
docker pull ghcr.io/valknarxxx/sexy:latest
|
||||
docker stop sexy-pivoine
|
||||
docker rm sexy-pivoine
|
||||
# Then re-run the docker run command from Step 3
|
||||
|
||||
# Docker Compose
|
||||
docker-compose -f docker-compose.production.yml pull
|
||||
docker-compose -f docker-compose.production.yml up -d
|
||||
```
|
||||
|
||||
### Shell Access
|
||||
|
||||
```bash
|
||||
# Docker Run
|
||||
docker exec -it sexy-pivoine sh
|
||||
|
||||
# Docker Compose
|
||||
docker-compose -f docker-compose.production.yml exec frontend sh
|
||||
```
|
||||
|
||||
## Available Image Tags
|
||||
|
||||
| Tag | Description | Use Case |
|
||||
|-----|-------------|----------|
|
||||
| `latest` | Latest stable build from main | Production |
|
||||
| `v1.0.0` | Specific version | Production (pinned) |
|
||||
| `develop` | Latest from develop branch | Staging |
|
||||
| `main-abc123` | Specific commit | Testing |
|
||||
|
||||
**Best Practice:** Use version tags in production for predictable deployments.
|
||||
|
||||
## Production Deployment
|
||||
|
||||
### 1. Use Version Tags
|
||||
|
||||
```bash
|
||||
# Instead of :latest
|
||||
docker pull ghcr.io/valknarxxx/sexy:v1.0.0
|
||||
```
|
||||
|
||||
### 2. Add Resource Limits
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name sexy-pivoine \
|
||||
-p 3000:3000 \
|
||||
--env-file .env.production \
|
||||
--memory="2g" \
|
||||
--cpus="2" \
|
||||
--restart unless-stopped \
|
||||
ghcr.io/valknarxxx/sexy:v1.0.0
|
||||
```
|
||||
|
||||
### 3. Use a Reverse Proxy
|
||||
|
||||
Example with nginx:
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 80;
|
||||
server_name sexy.pivoine.art;
|
||||
|
||||
location / {
|
||||
proxy_pass http://localhost:3000;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection 'upgrade';
|
||||
proxy_set_header Host $host;
|
||||
proxy_cache_bypass $http_upgrade;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Enable HTTPS
|
||||
|
||||
Use Certbot or similar:
|
||||
|
||||
```bash
|
||||
certbot --nginx -d sexy.pivoine.art
|
||||
```
|
||||
|
||||
## Health Check
|
||||
|
||||
The container includes a built-in health check:
|
||||
|
||||
```bash
|
||||
# Check container health
|
||||
docker inspect --format='{{.State.Health.Status}}' sexy-pivoine
|
||||
```
|
||||
|
||||
Possible statuses:
|
||||
- `starting` - Container just started
|
||||
- `healthy` - Application is responding
|
||||
- `unhealthy` - Application is not responding
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Container Exits Immediately
|
||||
|
||||
```bash
|
||||
# Check logs
|
||||
docker logs sexy-pivoine
|
||||
|
||||
# Common issues:
|
||||
# - Missing environment variables
|
||||
# - Port 3000 already in use
|
||||
# - Invalid environment variable values
|
||||
```
|
||||
|
||||
### Cannot Pull Image
|
||||
|
||||
```bash
|
||||
# For private images, ensure you're logged in
|
||||
docker login ghcr.io
|
||||
|
||||
# Check if image exists
|
||||
docker pull ghcr.io/valknarxxx/sexy:latest
|
||||
```
|
||||
|
||||
### Port Already in Use
|
||||
|
||||
```bash
|
||||
# Use a different port
|
||||
docker run -d -p 8080:3000 ghcr.io/valknarxxx/sexy:latest
|
||||
|
||||
# Or find what's using port 3000
|
||||
lsof -i :3000
|
||||
```
|
||||
|
||||
### Application Not Accessible
|
||||
|
||||
```bash
|
||||
# Check if container is running
|
||||
docker ps | grep sexy-pivoine
|
||||
|
||||
# Check logs
|
||||
docker logs sexy-pivoine
|
||||
|
||||
# Verify port mapping
|
||||
docker port sexy-pivoine
|
||||
|
||||
# Test from inside container
|
||||
docker exec sexy-pivoine wget -O- http://localhost:3000
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
- **Production setup:** See [DOCKER.md](DOCKER.md)
|
||||
- **Development:** See [CLAUDE.md](CLAUDE.md)
|
||||
- **CI/CD:** See [.github/workflows/README.md](.github/workflows/README.md)
|
||||
|
||||
## Support
|
||||
|
||||
- **Issues:** https://github.com/valknarxxx/sexy/issues
|
||||
- **Discussions:** https://github.com/valknarxxx/sexy/discussions
|
||||
- **Security:** Report privately via GitHub Security tab
|
||||
|
||||
## License
|
||||
|
||||
See [LICENSE](LICENSE) file for details.
|
||||
Reference in New Issue
Block a user