Skip to main content
wit includes a complete self-hosted platform that provides Git hosting, pull requests, issues, and a web UI. Start everything with a single command.

​
Quick Start

# Start the entire platform
wit up

# Stop everything
wit down
That’s it. wit handles database setup, migrations, and all services.

​
wit up

Start the wit platform with all services. 
wit up [options]
OptionDescription
--port <port>API server port (default: 3000)
--db-port <port>Database port (default: 5432)
--no-webDon’t start the web UI
--no-dbUse external database (requires DATABASE_URL)
--data-dir <dir>Data directory (default: ~/.wit)
-h, --helpShow help message

​
What wit up Does

  1. Starts PostgreSQL via Docker (or connects to external DB)
  2. Runs database migrations automatically
  3. Starts the API server for Git operations and tRPC API
  4. Starts the web UI (Vite dev server)

​
Examples

# Start everything on default ports
wit up

# Start server on port 8080
wit up --port 8080

# Start without web UI (API only)
wit up --no-web

# Use custom data directory
wit up --data-dir ./my-wit-data

# Use external database
DATABASE_URL="postgresql://user:pass@host:5432/wit" wit up --no-db

​
Output

When successfully started: 
🚀 Starting wit platform...

  Starting database...
  ✓ Database started
  Running migrations...
  ✓ Migrations complete
  Starting API server...
  ✓ API server started
  Starting web UI...
  ✓ Web UI started

✓ wit is running!

  Services:
    API:      http://localhost:3000
    Web UI:   http://localhost:5173
    Database: localhost:5432

  Stop with: wit down
  Logs at:   ~/.wit/logs

​
wit down

Stop the wit platform. 
wit down [options]
OptionDescription
--keep-dbDon’t stop the database
--remove-dataRemove all data (DESTRUCTIVE)
-h, --helpShow help message

​
Examples

# Stop all services
wit down

# Stop but keep database running
wit down --keep-db

# Stop and delete all data
wit down --remove-data

​
wit platform-status

Check the status of running services. 
wit platform-status
Shows which services are running and their health.

​
Data Directory

All platform data is stored in ~/.wit by default: 
~/.wit/
├── repos/          # Git repositories
├── db/             # PostgreSQL data
├── logs/           # Service logs
│   ├── server.log
│   └── web.log
└── wit.pid         # Process IDs

​
Custom Data Directory

Use --data-dir to specify a different location: 
wit up --data-dir /var/lib/wit

​
Requirements

​
Docker

wit uses Docker to run PostgreSQL. Install Docker from docker.com. Check if Docker is installed: 
docker --version

​
External Database (Optional)

If you prefer to use an existing PostgreSQL database: 
export DATABASE_URL="postgresql://user:password@localhost:5432/wit"
wit up --no-db
The database must be PostgreSQL 14 or later.

​
Configuration

​
Environment Variables

VariableDescriptionDefault
DATABASE_URLPostgreSQL connection stringAuto-configured
PORTAPI server port3000
REPOS_DIRRepository storage path~/.wit/repos
JWT_SECRETSecret for JWT tokensAuto-generated
NODE_ENVEnvironment modeproduction

​
Using with External Services

To integrate with external services, set the appropriate environment variables before running wit up: 
# Use external database
export DATABASE_URL="postgresql://user:pass@db.example.com:5432/wit"

# Use custom JWT secret
export JWT_SECRET="your-secret-key-here"

# Start with external database
wit up --no-db

​
Production Deployment

For production deployments, consider:

​
Using Docker Compose

Create a docker-compose.yml: 
version: '3.8'

services:
  wit-server:
    build: .
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgresql://wit:wit@db:5432/wit
      - JWT_SECRET=${JWT_SECRET}
      - NODE_ENV=production
    volumes:
      - wit-repos:/app/repos
    depends_on:
      - db

  db:
    image: postgres:16-alpine
    environment:
      - POSTGRES_USER=wit
      - POSTGRES_PASSWORD=wit
      - POSTGRES_DB=wit
    volumes:
      - wit-db:/var/lib/postgresql/data

  web:
    build: ./apps/web
    ports:
      - "5173:5173"
    environment:
      - VITE_API_URL=http://wit-server:3000/trpc

volumes:
  wit-repos:
  wit-db:
Run with: 
docker-compose up -d

​
Nginx Reverse Proxy

For production with HTTPS: 
server {
    listen 443 ssl;
    server_name git.example.com;

    ssl_certificate /etc/letsencrypt/live/git.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/git.example.com/privkey.pem;

    # Git operations
    location ~ ^/([^/]+)/([^/]+)\.git {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        
        # Required for Git operations
        proxy_buffering off;
        client_max_body_size 0;
    }

    # API
    location /trpc {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # Web UI
    location / {
        proxy_pass http://localhost:5173;
        proxy_set_header Host $host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

​
Troubleshooting

​
Port Already in Use

Error: Server failed to start on port 3000
Either stop the existing service or use a different port: 
wit up --port 8080

​
Docker Not Found

Error: Docker is required to run the database
Install Docker or use an external database: 
DATABASE_URL="postgresql://..." wit up --no-db

​
Database Connection Failed

Check the logs: 
cat ~/.wit/logs/server.log
Verify PostgreSQL is running: 
docker ps | grep wit-postgres

​
Checking Logs

Service logs are stored in ~/.wit/logs/: 
# API server logs
tail -f ~/.wit/logs/server.log

# Web UI logs
tail -f ~/.wit/logs/web.log

​
Cleaning Up

To completely reset the platform: 
wit down --remove-data
This removes all data including repositories and database content.