Skip to main content

Quick Start Guide

Get Chirp running in minutes with this quick start guide. We'll cover the fastest way to get a development environment up and running.

The fastest way to try Chirp is with Docker and Docker Compose.

1. Clone the Repository​

git clone https://git.eidenz.moe/Eidenz/chirp.git
cd chirp

2. Set up Environment​

Optionally create a .env file next to docker-compose.yml with your server's public IP (needed for voice channels):

echo "TURN_EXTERNAL_IP=your.public.ip" > .env

3. Start with Docker​

docker compose up -d

This will:

  • Start PostgreSQL database
  • Start Redis for caching
  • Build and start Chirp (backend + frontend)
  • Start Coturn TURN server for voice channels

4. Access Chirp​

5. Create First Account​

  1. Open http://localhost:8080 in your browser
  2. Click "Register"
  3. Create your account

Note: If email is not configured, check server logs for the verification link: docker compose logs chirp

Option 2: Manual Installation​

Prerequisites​

1. Clone and Install Dependencies​

git clone https://git.eidenz.moe/Eidenz/chirp.git
cd chirp
npm install

2. Set up Database​

# Create database and user
sudo -u postgres psql
CREATE DATABASE chirp_dev;
CREATE USER chirp_dev WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE chirp_dev TO chirp_dev;
\q

Configure server/.env:

cp server/.env.example server/.env

Edit server/.env:

DB_HOST=localhost
DB_PORT=5432
DB_USER=chirp_dev
DB_PASSWORD=your_password
DB_NAME=chirp_dev
DB_SSL=false

3. Set JWT Secret​

Generate a secure JWT secret:

node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"

Add it to server/.env:

JWT_SECRET=your_generated_secret_here

4. Run Database Migrations​

npm run db:migrate

5. Start Development Servers​

# Start backend + frontend (recommended)
npm run dev

# Or start individually:
# npm run dev:server   # Backend only (port 3001)
# npm run dev:web      # Frontend only (port 5173)
# npm run dev:electron # Backend + Frontend + Desktop app

6. Access Chirp​

Verify Installation​

Once Chirp is running, you should see:

Backend Server​

Server running on port 3001

Frontend Development Server​

VITE vX.X.X ready in XXX ms
  ➜  Local:   http://localhost:5173/

Troubleshooting​

Common Issues​

Port already in use?

# Kill processes on ports 3001 or 5173
# Linux/Mac:
sudo lsof -ti:3001 | xargs kill -9
sudo lsof -ti:5173 | xargs kill -9

# Windows:
netstat -ano | findstr :3001
taskkill /PID <PID> /F

Database connection failed?

  • Check PostgreSQL is running
  • Verify database credentials in server/.env
  • Ensure database was created

Frontend not loading?

  • Check Node.js version (v18+)
  • Delete node_modules and run npm install again
  • Clear browser cache

Migration errors?

npm run db:rollback  # Rollback last migration
npm run db:migrate   # Try again

Getting Help​

  • Check the logs: docker compose logs chirp or look at terminal output
  • Git Issues: Report problems

Ready to explore? Learn about basic usage or configure for production.