Docker 部署

Deploy Next.js, Nuxt.js, and TanStack Start applications using Docker and Docker Compose

This guide explains how to deploy TinyShip's Next.js, Nuxt.js, and TanStack Start 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, Nuxt.js, or TanStack Start applications:

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

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

# Start TanStack Start application
docker compose --profile tanstack 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

TanStack Start Deployment

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

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

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

# Start TanStack Start application
docker compose --profile tanstack 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
docker logs tinyship-tanstack

# 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