User GuideDeployment
Traditional Deployment
Traditional deployment on VPS servers
Traditional deployment is suitable for scenarios requiring full server control. It can be used for Next.js, Nuxt.js, and TanStack Start.
Prerequisites
- Linux server (Ubuntu 22.04 recommended)
- Node.js >= 22.20.0
- PNPM >= 9.0.0
- PostgreSQL >= 13
- Nginx (reverse proxy)
- PM2 (process management)
Deployment Steps
1. Install Dependencies
# Install Node.js
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
# Install PNPM
npm install -g pnpm
# Install PM2
npm install -g pm22. Clone Project
cd /var/www
git clone https://github.com/your/tinyship.git
cd tinyship3. Install Dependencies and Build
pnpm install
pnpm run build:next # or pnpm run build:nuxt / pnpm run build:tanstack4. Configure Environment Variables
cp env.example .env
nano .env # Edit production environment variables5. Initialize Database
pnpm run db:push
pnpm run db:seed # Optional6. Start with PM2
# Start Next.js application
pm2 start npm --name "tinyship" -- run start:next
# Start Nuxt.js / TanStack Start
# pm2 start npm --name "tinyship-nuxt" -- run start:nuxt
# pm2 start npm --name "tinyship-tanstack" -- run start:tanstack
# Save process list
pm2 save
# Set startup on boot
pm2 startupNginx Configuration
server {
listen 80;
server_name yourdomain.com;
return 301 https://$server_name$request_uri;
}
server {
listen 443 ssl http2;
server_name yourdomain.com;
ssl_certificate /etc/ssl/certs/your-cert.pem;
ssl_certificate_key /etc/ssl/private/your-key.pem;
location / {
proxy_pass http://localhost:7001;
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;
}
}Common Commands
# View app status
pm2 status
# View logs
pm2 logs tinyship
# Restart app
pm2 restart tinyship
# Update code and restart
git pull && pnpm install && pnpm run build:next && pm2 restart tinyshipAutomated Deployment
Consider using CI/CD tools (like GitHub Actions) for automated deployment.
Troubleshooting
Next.js listens on port 7001 (next start --port 7001). Nuxt uses the same port in nuxt.config.ts. Point Nginx proxy_pass at http://localhost:7001. The Chinese page still shows port 3000; that does not match the app.
| Symptom | What to check |
|---|---|
| 502 from Nginx | proxy_pass port is 7001, and pm2 status shows the process online |
| App exits on boot | .env was copied from env.example, and DATABASE_URL reaches Postgres |
| Auth redirects to localhost | BETTER_AUTH_URL and APP_BASE_URL are the public https origin |
Blank page after git pull | Rebuild (pnpm run build:next or pnpm run build:nuxt) before pm2 restart |