Quickstart

Get the Project Zoe server and client running locally in under 10 minutes.

Prerequisites

• Node.js 20+ — nodejs.org
• PostgreSQL running locally
• Redis running locally (used for caching; default port 6379)

---

1. Start the server

1. Clone and install

   git clone https://github.com/kanzucodefoundation/project-zoe-server.git
   cd project-zoe-server
   git checkout develop
   npm install
   
2. Configure environment

   cp .env.sample .env
   

   Open .env and fill in at minimum:

   Variable	Value
   DB_USERNAME	Your Postgres username
   DB_PASSWORD	Your Postgres password
   DB_DATABASE	projectzoe-db (or your choice)
   APP_ENVIRONMENT	local
   JWT_SECRET	Any long random string
   REDIS_HOST	localhost
   REDIS_PORT	6379

3. Create the database

   createdb projectzoe-db
   
4. Start the server

   npm run start:dev
   

   The API is available at http://localhost:4002.

5. Seed demo data

   Create a demo tenant and seed it with realistic contacts, groups, and reports:

   npm run command create-tenant demo
   npm run seed:comprehensive
   

   This creates 7 test accounts, a 6-level group hierarchy, 50+ contacts, and 500+ report submissions. All test accounts use password password123.

   Email	Role
   [e-mail]	System Admin
   [e-mail]	Movement Leader
   [e-mail]	Location Pastor
   [e-mail]	Zone Leader
   [e-mail]	MC Shepherd

---

2. Start the client

1. Clone and install

   git clone https://github.com/kanzucodefoundation/project-zoe-client.git
   cd project-zoe-client
   git checkout develop
   npm install
   
2. Configure environment

   cp .env.sample .env
   

   Set VITE_API_URL=http://localhost:4002.

3. Start the dev server

   npm run dev
   

   The app opens at http://localhost:5173.

---

3. Log in

Navigate to http://localhost:5173 and log in with:

• Church name: demo
• Email: [e-mail]
• Password: password123

Try logging in with different accounts (e.g. [e-mail]) to see how role-based access scopes data to each leader’s part of the group hierarchy.

---

Next steps

Architecture

Understand multi-tenancy, the group tree, and the auth model.

API Reference

Explore available REST endpoints.

Database & Migrations

How schema changes and migrations work.

Contributing

How to submit a bug fix or feature.