Skip to main content

​
Prerequisites

Before you begin, ensure you have the following tools installed on your system:

Node.js

Version 18 or higher for frontend development

Go

Version 1.25.1 or higher for backend development

Docker

For running PostgreSQL database locally

Make

Build automation tool (pre-installed on macOS/Linux)
Optional tools:
  • Air: For Go hot-reloading during development
  • Caddy: Reverse proxy for local development
  • golangci-lint: For code linting
For detailed installation instructions for each prerequisite, see the Installation Guide.

​
Installation Steps

1

Clone the repository

Clone the Reservations repository to your local machine:
git clone https://github.com/Miketsu-inc/reservations.git
cd reservations
2

Install dependencies

Install both Node.js and Go dependencies:
npm install
go mod tidy
3

Configure environment variables

Create a .env file in the project root with the required configuration:
# Application
PORT=8080
APP_ENV=development

# Database
DB_HOST=localhost
DB_PORT=5432
DB_DATABASE=reservations
DB_USERNAME=postgres
DB_PASSWORD=postgres
DB_SCHEMA=public

# JWT Authentication
JWT_ACCESS_SECRET=your-access-secret-key-here
JWT_ACCESS_EXP_MIN=15
JWT_REFRESH_SECRET=your-refresh-secret-key-here
JWT_REFRESH_EXP_MIN=10080

# Email (Resend)
RESEND_API_TEST=your-resend-api-key
ENABLE_EMAILS=true

# OAuth (optional for quickstart)
GOOGLE_OAUTH_CLIENT_ID=your-google-client-id
GOOGLE_OAUTH_CLIENT_SECRET=your-google-client-secret
FACEBOOK_OAUTH_CLIENT_ID=your-facebook-client-id
FACEBOOK_OAUTH_CLIENT_SECRET=your-facebook-client-secret

# Frontend
VITE_MAPBOX_TOKEN=your-mapbox-token
Replace placeholder values with actual credentials. For JWT secrets, use strong random strings. For quickstart purposes, you can use dummy values for OAuth and Mapbox if you don’t need those features immediately.
See the Environment Configuration guide for detailed explanations of each variable.
4

Create the database

Create a PostgreSQL database with PostGIS extension using Docker:
make create-db
This command creates a Docker container named postgresdb with PostgreSQL and PostGIS extension.
The database will be created with the credentials specified in your .env file. The container will persist data in a Docker volume named pgdata.
5

Run the development server

Start all development services in parallel:
make run
This single command starts 7 processes concurrently:
  • Vite dev server for Jabulani (merchant app) on port 5173
  • Vite dev server for Tango (customer app) on port 5174
  • Tailwind CSS compiler for Jabulani
  • Tailwind CSS compiler for Tango
  • Air hot-reload for Go backend
  • PostgreSQL database container
  • Caddy reverse proxy
The first run may take a minute to compile everything. Subsequent runs will be faster thanks to Go’s build cache and Vite’s HMR.

​
Verify Installation

Once all services are running, verify your installation:
Test the backend API is running:
curl http://localhost:8080/health
You should receive a successful response from the health check endpoint.

​
Development Workflow

​
Making Code Changes

The development environment includes hot-reloading for rapid iteration:
  • Frontend Changes: Vite will automatically reload the browser when you save React components
  • CSS Changes: Tailwind CSS will recompile automatically
  • Backend Changes: Air will detect changes and rebuild the Go binary

​
Running Individual Services

If you need to run services separately for debugging: 
# Run only the backend
make air

# Run only Jabulani frontend
make vite-jabulani

# Run only Tango frontend  
make vite-tango

# Run only database
make db

​
Stopping Services

Press Ctrl+C in the terminal where make run is running to stop all services. To stop the database container: 
docker stop postgresdb

​
Building for Production

When you’re ready to create a production build: 
make build
This will:
  1. Compile and minify Tailwind CSS for both apps
  2. Build optimized production bundles for Jabulani and Tango
  3. Export email templates
  4. Compile the Go backend with production tags
The final binary will be at backend/bin/reservations and includes embedded frontend assets.

​
Next Steps

Architecture Overview

Learn about the system architecture and how components interact

Database Setup

Understand the database schema and migrations

Backend Development

Explore the Go backend structure and patterns

Frontend Development

Learn about the React applications and shared packages

​
Troubleshooting

If you see an error that ports 5173, 5174, or 8080 are already in use, stop any services using those ports or change the port numbers in your configuration.
Ensure the PostgreSQL container is running with docker ps. If not, start it with make db or create it with make create-db.
If you see Go module errors, try clearing the cache and re-downloading:
go clean -modcache
go mod tidy
Clear your node_modules and reinstall:
rm -rf node_modules package-lock.json
npm install
Install Air globally:
go install github.com/air-verse/air@latest
Make sure $GOPATH/bin is in your PATH.

Build docs developers (and LLMs) love

Get started for freeTalk to us