Docker 部署

This guide explains how to deploy TinyShip's Next.js and Nuxt.js applications using Docker containers.

Prerequisites

Docker >= 20.10
Docker Compose >= 2.0

Recommended: Docker Compose

Use the docker-compose.yml file in the project root to start Next.js or Nuxt.js applications separately:

# Start Next.js application
docker compose --profile next up -d

# Start Nuxt.js application  
docker compose --profile nuxt up -d

# View logs
docker compose logs -f

# Stop application
docker compose down

Manual Docker Deployment

Next.js Deployment

# 1. Ensure .env file exists in project root, then build image
docker build -t tinyship-next -f apps/next-app/Dockerfile .

# 2. Run container
docker run -d \
  --name tinyship-next \
  -p 7001:7001 \
  --env-file .env \
  --restart unless-stopped \
  tinyship-next

Nuxt.js Deployment

# 1. Ensure .env file exists in project root, then build image
docker build -t tinyship-nuxt -f apps/nuxt-app/Dockerfile .

# 2. Run container
docker run -d \
  --name tinyship-nuxt \
  -p 7001:7001 \
  --env-file .env \
  --restart unless-stopped \
  tinyship-nuxt

Important Notes

Build Path

Must run docker build from project root directory
Use -f parameter to specify Dockerfile path
Build context is the project root (.)

Cross-Platform Builds

For building across different architectures (e.g., M1/M2 Mac building for AMD64 server):

# Build for specific platform
docker build --platform linux/amd64 -t tinyship-next -f apps/next-app/Dockerfile .

# Or build multi-platform image
docker buildx build --platform linux/amd64,linux/arm64 -t tinyship-next -f apps/next-app/Dockerfile .

Platform mappings:

Platform	Architecture
M1/M2 Mac	`linux/arm64`
Intel Mac/Windows/Linux	`linux/amd64`
Most cloud servers	`linux/amd64`

Build Dependencies

Dockerfile automatically copies these necessary config files:

turbo.json - Turbo build configuration
config.ts - Application configuration file
tsconfig.json - TypeScript path aliases
libs/ - Shared library directory

Build-time Environment Variables

Two build modes supported, auto-adapting to different environments:

Local Development Build

Dockerfile automatically copies .env file from project root (if exists)
Public frontend variables auto-read: NEXT_PUBLIC_TURNSTILE_SITE_KEY, NEXT_PUBLIC_WECHAT_APP_ID
No extra parameters needed, single command build

CI/CD Environment Build

Supports passing environment variables via --build-arg
Works in GitHub Actions/other CI environments without .env file
Priority: build args > .env file > default values

Database Connection Configuration

Docker containers cannot use localhost to connect to host services:

# Wrong - container cannot access host's localhost
DATABASE_URL=postgresql://localhost:5432/db

# Mac/Windows Docker Desktop:
DATABASE_URL=postgresql://viking@host.docker.internal:5432/tinyship_dev

# Linux VPS bridge mode:
DATABASE_URL=postgresql://viking@172.17.0.1:5432/tinyship_dev

# Linux VPS host network mode (recommended):
DATABASE_URL=postgresql://viking@localhost:5432/tinyship_dev

Linux VPS host network mode:

docker run -d \
  --name tinyship-nuxt \
  --network host \
  --env-file .env \
  --restart unless-stopped \
  tinyship-nuxt

Docker Compose Details

Commands

# Start Next.js application
docker compose --profile next up -d

# Start Nuxt.js application
docker compose --profile nuxt up -d

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

# View logs
docker compose logs -f

# Stop application
docker compose down

# View running status
docker compose ps

Restart Policy

--restart unless-stopped parameter means:

Container crashes: auto-restart
Docker service restarts: auto-restart container
Server restarts: auto-restart container
Manual stop: won't restart (docker stop)

Environment Variables Example

Create .env file for Docker deployment:

.env

NODE_ENV=production

# Database connection - choose based on your setup
# Mac/Windows Docker Desktop:
# DATABASE_URL=postgresql://viking@host.docker.internal:5432/tinyship_dev
# Linux VPS host network mode (recommended):
DATABASE_URL=postgresql://viking@localhost:5432/tinyship_dev

# Application URL - use actual access address
APP_BASE_URL=https://yourdomain.com
BETTER_AUTH_SECRET=your-production-secret-key
BETTER_AUTH_URL=https://yourdomain.com

Common Commands

# View running containers
docker ps

# View logs
docker logs tinyship-next
docker logs tinyship-nuxt

# Stop container
docker stop tinyship-next

# Remove container
docker rm tinyship-next

# Remove image
docker rmi tinyship-next

# Enter container for debugging
docker exec -it tinyship-next /bin/sh

# View container resource usage
docker stats

# Clean unused images and containers
docker system prune

Troubleshooting

Common Issues

Issue	Solution
Build fails - lockfile incompatible	Check pnpm version, update pnpm version in Dockerfile
Cannot find turbo.json	Ensure running docker build from project root
Database connection failed	Check `host.docker.internal` config and username
Port already in use	Change port mapping or stop service using the port
Environment variables not applied	Check `.env` file path and format
Platform architecture mismatch	Use `--platform` parameter to specify target platform

Log Debugging

# View build process logs
docker build -t tinyship-next -f apps/next-app/Dockerfile . --no-cache

# Check image platform architecture
docker image inspect tinyship-next --format='{{.Architecture}}'

# View container startup logs
docker logs tinyship-next --follow

# View Docker Compose logs
docker compose logs -f --tail=100

Performance Optimization

# Set resource limits
docker run -d \
  --name tinyship-next \
  --memory=1g \
  --cpus=0.5 \
  -p 7001:7001 \
  tinyship-next

Back to Deployment Overview