Local Development with Docker

This guide provides detailed instructions for setting up Hi.Events using Docker, including requirements, setup steps, additional configuration, and environment variables.

Requirements

Docker: Docker simplifies the management and deployment of applications. Get Docker.
Docker Compose v2: The setup script uses the docker compose (v2 plugin) command, not the legacy docker-compose binary. It comes with Docker Desktop for Windows and Mac. Docker Compose Installation Guide.
Git: Git must be installed to clone the repository. Git Installation Guide.
OpenSSL: The setup script calls openssl directly to generate the local SSL certificate. It is preinstalled on most macOS and Linux systems.

ℹ️

The start-dev.sh script is a bash script, so it doesn’t run natively on Windows. Windows users should follow the manual step-by-step instructions in docker/development/README.md, which cover the same steps individually.

Setup Instructions

Step 1: Clone the Repository

Clone the Hi.Events GitHub repository to your local machine using Git:

git clone https://github.com/HiEventsDev/hi.events.git

Step 2: Run the Installation Script

Change to the Docker directory in the cloned repository and start the environment:

cd hi.events/docker/development
./start-dev.sh

The script is interactive and will ask you four questions:

Wipe the database and start fresh? (default n) — answering y tears down the containers and volumes, so you lose all local data.
Reinstall frontend dependencies (yarn install)? (default y) — rebuilds the frontend image with fresh dependencies. Answer n to skip when nothing has changed in package.json.
Start the queue worker? (default y) — runs php artisan queue:work --queue=default,webhook-queue,occurrences.
Start the scheduler? (default y) — runs php artisan schedule:work.

⚠️

Keep the queue worker and scheduler running. Without them, queued work never executes — outgoing emails, webhook deliveries and recurring-event occurrence generation will silently do nothing, and scheduled jobs won’t run. If you skipped them, the script prints the commands to start them later.

After starting, access the app at:

Frontend: https://localhost:8443
Backend/API: https://localhost:8443/api

Additional Configuration

Adjust configurations based on your setup for mail service, object storage, and application settings through environment variables.

Environment Configuration

Hi.Events uses three separate .env files in local development, and it’s important to know which one to edit:

File	What it’s for
`docker/development/.env`	Docker Compose only. These values are substituted into `docker-compose.dev.yml` — the app name, API and frontend URLs, the Stripe publishable key passed to the frontend, and the PostgreSQL credentials. Only `APP_ENV` and `APP_KEY` are passed through to the backend container.
`backend/.env`	Backend application config. Mail service, object storage (S3/MinIO), Stripe secret and webhook keys, and everything else Laravel reads.
`frontend/.env`	Frontend application config.

⚠️

Mail, object storage and Stripe secrets belong in backend/.env, not docker/development/.env. Changing them in the Docker Compose file will have no effect on the backend.

The start-dev.sh script creates backend/.env and frontend/.env from their respective .env.example files on first run, if they don’t already exist.

For a breakdown of the available environment variables, refer to the Environment Variables Documentation.

Stripe Webhooks

To test Stripe end-to-end, you’ll need to use the Stripe CLI to forward webhooks to your local environment. Follow the instructions in the Stripe CLI Webhooks Documentation.

The following command should start the listener locally.

stripe listen --forward-to https://127.0.0.1:8443/api/public/webhooks/stripe --skip-verify

Port 8443 is the TLS port and uses a self-signed certificate, which is why --skip-verify is needed. Alternatively, you can forward to the plain HTTP port instead:

stripe listen --forward-to http://127.0.0.1:8080/api/public/webhooks/stripe

Your Stripe secret and webhook signing keys go in backend/.env (STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET).

Reserved Seating and the Box Office

These are Enterprise features and stay off by default, even in development. To work on them, add this to backend/.env:

APP_LICENCE_KEY=development

That unlocks them for development and testing, and shows a “Development licence” notice once they’re in use. Remove the line to switch them off again.

Generating Signed Certificates for Localhost

By default, the ./start-dev.sh command will generate an unsigned SSL certificate for localhost. This is fine for development purposes; however, it results in browsers showing a warning when you first use the app.

If this is an issue for you, you can generate a signed certificate using mkcert.

⚠️

--certs=signed only generates certificates when none exist, so delete the ones created in Step 2 first.

# Install mkcert using instructions from the repository: https://github.com/FiloSottile/mkcert
mkcert -install
 
# Remove the existing unsigned certificates (run from the repository root)
rm -f docker/development/certs/localhost.crt docker/development/certs/localhost.key
 
cd docker/development
./start-dev.sh --certs=signed

Accessing Mail and Database Services

The Docker setup includes configurations for mail and database services. Below is an overview of the services and their configurations:

Mail Service (Mailpit)

Mailpit is included to handle emails during development. It is accessible at:

Mailpit Dashboard: http://localhost:8025

Database Service (PostgreSQL)

PostgreSQL is used as the database. Below are the connection details:

Host: localhost to connect from the host machine, or pgsql to connect from another container.
Port: 5432
Database: backend
Username: username
Password: password

By following these instructions and configurations, you will have a fully functional Hi.Events environment running locally with Docker, including mail and database services.

Deploying Enterprise Features