Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
148 lines (110 loc) · 4.84 KB

CONTRIBUTING.md

File metadata and controls

148 lines (110 loc) · 4.84 KB

Contributing

Thanks for your interest in contributing to V-Mail! You're most welcome to do so. The easiest way to contribute is to fork the repo, make your changes, and submit a PR. This doc is here to help you get started.

(This doc is a WIP. If you have questions, please open an issue.)

Development getting started

This setup lets you run the Go backend and the React frontend locally for debugging. It is different from the "Running" section of the main README, which uses Docker Compose for everything.

0. Install mise and tools

This project uses mise for tool version management. It automatically installs and manages the correct versions of Go, Node, and pnpm.

  1. Install mise:

    brew install mise

    See more alternatives here.

  2. In the project directory, install all required tools:

    mise install

    This will install Go, Node, and pnpm. The tools will be automatically available when you're in the project directory.

  3. Install golang-migrate separately (it's not available in mise's registry):

    brew install golang-migrate

    Alternatively, you can install it via Go:

    go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@latest

  4. Install development tools:

    • Overmind (process manager for running multiple services): 
      brew install overmind
      Or via Go: 
      go install github.com/DarthSim/overmind/v2/cmd/overmind@latest
    • Air (Go live reload): 
      go install github.com/air-verse/air@latest

1. Database

  1. Run a Postgres v14+ instance and make it available on a port (e.g., 5432). You can use Docker for this (note the random port 3436!): 
    docker run -d --name vmail-postgres -p 127.0.0.1:3436:5432 -e POSTGRES_USER=vmail -e POSTGRES_PASSWORD=vmail -e POSTGRES_DB=vmail postgres:18-alpine
  2. Run the migrations (customize this to your DB setup): 
    migrate -path backend/migrations -database "postgres://vmail:vmail@localhost:3436/vmail?sslmode=disable" up

2. Authentication

For local development, no authentication setup is needed. The backend runs in "dev" mode by default, which uses stub authentication (all requests are authenticated as test@example.com).

If you want to test with real Authelia integration, see the README for setup options.

3. Configuration

  1. Copy .env.example to .env in the project root: 
    cp .env.example .env
  2. Edit .env to match your local setup:
    • Set VMAIL_DB_PORT to 3436 if you used the suggested Docker command above.
    • Set VMAIL_DB_PASSWORD to vmail if you used the suggested Docker command above.
    • Optionally set the other VMAIL_DB_* settings too if you prefer a different DB setup.
    • Set VMAIL_ENCRYPTION_KEY_BASE64 – generate with openssl rand -base64 32.

4. Running the application

Quick start (recommended)

After setting up the database and configuration, run both the backend and frontend with live reload:

overmind start -f Procfile.dev

This will:

  • Start the Go backend on http://localhost:11764 with automatic reload on code changes (using air)
  • Start the React frontend on http://localhost:7556 (or the port configured in VITE_PORT) with hot module replacement (Vite)
  • Display prefixed logs from both processes in a single terminal

Press Ctrl+C to stop both servers.

Note: Overmind uses tmux under the hood. You can connect to individual processes if needed:

overmind connect backend  # Connect to backend process
overmind connect frontend # Connect to frontend process

Alternatively, to only run the front end or back end:

cd frontend && pnpm dev                 # Frontend
cd backend && go run cmd/server/main.go # Backend without live reload (for line-to-line debugging in IntelliJ/GoLand)
cd backend && PORT=11764 air            # Backend with live reload

Running services separately

If you prefer to run the backend and frontend in separate terminals:

Backend (with live reload):

air

Or without live reload:

go run backend/cmd/server/main.go

Frontend:

cd frontend
pnpm install  # First time only
pnpm dev

Tooling

The project includes several utility scripts in scripts/. See docs/scripts for their docs.

Testing

scripts/check.sh runs all formatting, linting, and tests. Always run it before committing and ensure all checks pass. See ./scripts/check.sh --help to learn about more specific uses.

Keeping things up to date

For a step-by-step process on updating tools, dependencies, and Docker images, see docs/maintenance.md.