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​

Copy the example environment file:

cp server/.env.example server/.env

3. Start with Docker​

docker-compose up -d

This will:

  • Start PostgreSQL database
  • Start Redis for caching
  • Start Chirp backend server
  • Build and start the web frontend

4. Access Chirp​

5. Create First Account​

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

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​

cd server
npm run db:migrate
cd ..

5. Start Development Servers​

# Start all services (recommended)
npm run dev

# Or start individually:
# npm run dev:server   # Backend only
# npm run dev:web      # Frontend only
# npm run dev:electron # Backend/Frontend & Desktop app

6. Access Chirp​

Verify Installation​

Once Chirp is running, you should see:

Backend Server​

🚀 Chirp server running on port 3001
📡 Database connected
🔌 Socket.IO server started

Frontend Development Server​

✨ Vite server running at http://localhost:5173

Next Steps​

🎉 Congratulations!​

You now have Chirp running locally. Here's what to do next:

Troubleshooting​

Common Issues​

Port already in use?

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

Database connection failed?

  • Check PostgreSQL is running
  • Verify database credentials in .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?

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

Getting Help​

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

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