volunteer-scheduler

Repo for the Volunteer Scheduler project.

To understand why this project exists and how it differs from existing solutions, start with Vision and Purpose.

Tech Stack

The volunteer-scheduler is a Next.js and React-based web application.

We use Payload CMS as an out-of-the-box backend - it provides an admin panel, database abstractions, an API, and a lot more that we would otherwise have to build ourselves.

The frontend is built with Park UI (Panda CSS & Ark UI), and uses API endpoints and interfaces exposed by Payload.

How to get started with development

Important

This guide is tested on macOS & Linux. If you run into steps that work differently on Windows, please open a PR to improve it.

Prerequisites

Install the following prerequisites:

1. docker runtime, pick one:

   • Docker "Engine"
   • Docker Desktop
     • macOS tip: brew install --cask rancher
   • Rancher Desktop
     • macOS tip: brew install --cask docker-desktop

2. optionally, get the Bun Javascript Runtime

   • macOS Homebrew: brew tap oven-sh/bun; brew install bun

Payload compatibility with the Bun Runtime

Payload only officially supports the Node.js runtime. However, the Payload CLI seems to work with Bun without issues when using the --disable-transpile option as documented in using alternative runtimes with Payload.

This is only relevant for the use of the payload cli during development and not for the build process. See this issue for details.

Run the project locally

1. Clone the repository:

   git clone git@github.com:desering/volunteer-scheduler.git

2. Because of macOS, and its BSD sed:

   source .github/scripts/functions.sh

3. Create a .env file and generate a secret key for Payload:

   cp .env.example .env
   sedi -e "s/PAYLOAD_SECRET_PLACEHOLDER/$(openssl rand -hex 32)/g" .env

Then choose between:

Run the project locally with docker only

with docker only

4. Start development services (database, mail, bun):

   docker compose --profile bun up

5. If your dependencies change, rebuild the image:

   docker compose --profile bun build

   and restart docker compose

This configuration stores your local build cache (.next) in a dedicated volume and node_modules are in the docker bun image.

Run the project locally using standalone bun

using standalone bun

4. Replace docker container names with localhost

   sedi '/^SMTP_HOST=/s|maildev|localhost|' .env
   sedi '/^DATABASE_URI=/s|@postgres:|@localhost:|' .env

5. Install all dependencies:

   bun install

6. Start additional development services (database, mail):

   docker compose up

7. Start the Next.js development server:

   bun --bun dev

This configuration stores your local build cache (.next) and node_modules in your host filesystem.

You should now be able to access your local version of volunteer-scheduler at http://localhost:3000/.

Create a user and events

When starting the app for the first time or after resetting the database, you will have to first create an admin user to access the backend and create events:

1. Open http://localhost:3000/admin/create-first-user
2. Fill in the form and make sure to select admin as the user role

Now, you can create and publish new events, which will show up in the frontend.

Working with the database

To connect to the PostgreSQL database container of your local development environment:

docker compose exec postgres psql -U schedule

Check out our PostgreSQL Cheat Sheet!

Working with mail

Payload requires an external mail server to send emails like password resets or shift reminders. To view emails sent from your local development environment, use MailDev:

• with above dev docker compose it should be running on http://localhost:1080/#/