User Guide
Getting Started
Set up and run TinyShip project in your local environment
This guide will help you set up and run the TinyShip project in your local environment.
System Requirements
Before starting, ensure your development environment meets the following requirements:
- Node.js: >= 22.20.0 (Must use 22.20.0 or higher LTS version)
- PNPM: >= 9.0.0 (Recommended package manager)
- PostgreSQL: >= 13.0 (Database)
Due to oxc-parser native binding issues with Nuxt 4, Node.js version must be >= 22.20.0. Lower versions may cause installation failures.
Quick Installation
Clone the Project
git clone https://github.com/TinyshipCN/tinyship.git
cd tinyship
# Or use SSH
git clone git@github.com:TinyshipCN/tinyship.git
cd tinyshipInstall PNPM (if not installed)
# Install pnpm using npm
npm install -g pnpm
# Or use corepack (Node.js 16.10+)
corepack enable
corepack prepare pnpm@latest --activate
# Verify installation
pnpm --versionCopy Environment Variables Template
cp env.example .envInstall Project Dependencies
pnpm installDatabase Configuration
TinyShip uses PostgreSQL as the primary database with Drizzle ORM for type-safe operations.
Create PostgreSQL Database
Method 1: Using Docker (Recommended)
docker run --name tinyship-db \
-e POSTGRES_USER=tinyship \
-e POSTGRES_PASSWORD=your_password \
-e POSTGRES_DB=tinyship \
-p 5432:5432 \
-d postgres:15
# Verify container is running
docker ps | grep tinyship-dbMethod 2: Local Installation
sudo -u postgres createuser --interactive tinyship
sudo -u postgres createdb tinyship --owner=tinyship
sudo -u postgres psql -c "ALTER USER tinyship PASSWORD 'your_password';"Method 3: Cloud Database Service
Supported cloud providers:
- Vercel Postgres: Seamless integration with Vercel deployment
- Supabase: Free tier available, easy setup
- AWS RDS: Enterprise-grade option
Configure Environment Variables
Configure database connection in your .env file:
DATABASE_URL="postgresql://username:password@localhost:5432/tinyship"pnpm run db:checkInitialize Database Schema
pnpm run db:pushSeed Test Data
pnpm run db:seedThis creates two test users:
- Admin:
admin@example.com/admin123(role: admin) - User:
user@example.com/user123456(role: user)
Minimal Auth Configuration
Configure authentication environment variables in .env:
BETTER_AUTH_SECRET="your-secret-key-here-32-characters-min"
BETTER_AUTH_URL="http://localhost:7001"
DATABASE_URL="postgresql://username:password@localhost:5432/tinyship"Generate 32-character random string:
# Using openssl
openssl rand -hex 32
# Using Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"Start the Application
# Start Next.js application
pnpm run dev:next
# Or start Nuxt.js application
pnpm run dev:nuxt
# Visit http://localhost:7001Congratulations! You have successfully run the TinyShip application.