Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Node.js 20+ - Runtime environment
  • pnpm 10 - Package manager
  • Docker - For running local Postgres
  • Slack app credentials - For OAuth authentication
  • Cloudflare account - With API token for tunnel + DNS permissions

​
Quick Start

Follow these steps to get rs-tunnel running on your local machine:
1

Install dependencies

Install all workspace dependencies using pnpm:
pnpm install
This installs dependencies for all packages in the monorepo.
2

Start Postgres

Start the local Postgres database using Docker Compose:
docker compose up -d postgres
This starts Postgres on port 23432 (mapped from container port 5432).
3

Configure environment variables

Create a .env file in the repository root or in apps/api/.env:
# Shared
API_BASE_URL=http://localhost:8080

# API
DATABASE_URL=postgres://postgres:postgres@localhost:23432/rs_tunnel
PORT=8080
JWT_SECRET=your-jwt-secret-here
REFRESH_TOKEN_SECRET=your-refresh-secret-here
SLACK_CLIENT_ID=your-slack-client-id
SLACK_CLIENT_SECRET=your-slack-client-secret
SLACK_REDIRECT_URI=http://localhost:8080/v1/auth/slack/callback
ALLOWED_EMAIL_DOMAIN=@example.com
ALLOWED_SLACK_TEAM_ID=T00000000
CLOUDFLARE_ACCOUNT_ID=your-account-id
CLOUDFLARE_ZONE_ID=your-zone-id
CLOUDFLARE_API_TOKEN=your-api-token
CLOUDFLARE_BASE_DOMAIN=tunnel.example.com
See .env.example in the repository root for a complete list of available configuration options.
4

Run database migrations

Apply database migrations to set up the schema:
pnpm --filter @ripeseed/api db:migrate
5

Start the API server

Start the API in development mode with hot reload:
pnpm --filter @ripeseed/api dev
The API will be available at http://localhost:8080.

​
Running the CLI Locally

To test CLI commands against your local API: 
export RS_TUNNEL_API_URL=http://localhost:8080
The CLI accepts a --domain flag to override the API URL per command. This setting is persisted to ~/.rs-tunnel/config.json for future runs.

​
Turbo Monorepo Commands

The project uses Turborepo for efficient task orchestration. Run commands from the repository root:

​
Development Mode

# Run all apps in parallel dev mode
pnpm dev

# Run specific package in dev mode
pnpm --filter @ripeseed/api dev
pnpm --filter @ripeseed/rs-tunnel dev

​
Quality Checks

# Run all checks
pnpm lint
pnpm typecheck
pnpm test
pnpm build

# Run checks for specific package
pnpm --filter @ripeseed/api lint
pnpm --filter @ripeseed/api test
Always run all quality checks before pushing code. These same checks run in CI and must pass.

​
Common Issues

The shared package must be built before dependent packages can use it.
pnpm --filter @ripeseed/shared build
The turbo dependency graph ensures typecheck depends on ^build, so this should happen automatically.
Ensure the Drizzle migration metadata exists:
ls apps/api/drizzle/meta/_journal.json
If missing, you may need to regenerate migrations.
Your DATABASE_URL is not properly configured or loaded.
  • Verify .env exists in repo root or apps/api/.env
  • Check that DATABASE_URL is complete and properly formatted
  • Ensure Docker Postgres is running on the correct port (23432)
The apps/cli/src/lib/local-proxy.test.ts test suite requires permission to bind to local sockets.Run tests in a normal local shell with appropriate permissions. This typically occurs in restricted or sandboxed environments.
Ensure SLACK_REDIRECT_URI in your .env exactly matches the redirect URI configured in your Slack app settings:
SLACK_REDIRECT_URI=http://localhost:8080/v1/auth/slack/callback

​
Next Steps

Monorepo Structure

Learn about the workspace structure and dependencies

Testing

Understand the testing strategy and run tests

Contributing

Learn how to contribute to rs-tunnel

API Reference

Explore the API endpoints

Build docs developers (and LLMs) love

Get started for freeTalk to us