Benemap — Volunteer Map for Everyone

An interactive map where volunteer organizations publish activities and volunteers find and join them nearby. Open source, non-commercial. Check it out on https://benemap.org/

Features

• Interactive map of volunteer activities, with clustering for nearby pins
• Anbieter (organizations) can register, publish activities (one-off or recurring), and manage their own listings
• Volunteers can sign up for activities directly in the app ("Ich mache mit")
• Rating system for activities and providers
• Städtische Angebote — scraped, undated listings from Cologne's municipal volunteer database, shown alongside app-native activities
• Category filtering, search by name/address, photo galleries
• Account self-service: profile photo/website, password reset via email, full self-deletion (GDPR-friendly)

Project Structure

/orga        // organization / documentation / planning files
/frontend    // Svelte 5 frontend (SPA, fetches data from backend)
/backend     // Spring Boot (Kotlin) backend (REST API + H2 database)

---

Tech Stack

• Frontend: Svelte 5 + TypeScript + Vite, Leaflet-based map (via sveaflet)
• Backend: Spring Boot + Kotlin, Spring Security (session auth), Spring Data JPA
• Database: H2 (file-based)
• Mail: SMTP via Brevo, for password-reset emails

---

How to Run (Development)

Backend (Spring Boot)

cd backend
./gradlew bootRun      # run Spring Boot

• Runs on http://localhost:8080
• Provides REST endpoints (e.g., /api/volunteers)
• Supports CORS for frontend development
• Starts with an empty map — no data is seeded automatically. To get some pins to look at: ./gradlew bootRun --args='--seed-fake' (30 fake activities) or ./gradlew bootRun --args='--scrape' (real listings scraped from Cologne's municipal volunteer database)

Frontend (Svelte)

cd frontend
npm install
npm run dev            # runs Svelte dev server

• Runs on http://localhost:5173
• Fetches data from backend via /api endpoints

Tests

cd backend && ./gradlew test      # backend test suite
cd frontend && npm run check      # type-check frontend

Production Build

• Build Svelte frontend:

cd frontend
npm run build

• Copy frontend/dist/ → backend/src/main/resources/static/
• Spring Boot will now serve both frontend (/) and backend (/api) from one server

Deployment

Production runs on a Netcup VPS (netcup1, 37.221.194.246) since 2026-09-11. Caddy terminates TLS for benemap.org and reverse-proxies to 127.0.0.1:48100 where Spring Boot listens as a local-only systemd service (/etc/systemd/system/benemap.service). The H2 database file lives at ~/services/benemap/data/volomap.mv.db; a daily backup runs at 03:00 via crontab → ~/services/benemap/backup.sh.

To deploy a new build from a workstation:

# One-time setup on the operator workstation:
cp deploy.sh.example deploy.sh             # local-only script (in .gitignore)
chmod +x deploy.sh
# edit deploy.sh and set BENEMAP_HOST / BENEMAP_SSH_KEY for your environment

# Then for each deploy:
./deploy.sh                                # build + test + deploy
SKIP_TESTS=1 ./deploy.sh                   # skip the backend test suite
BENEMAP_HOST=user@netcup1 BENEMAP_SSH_KEY=~/.ssh/id_ed25519 ./deploy.sh   # override target

The deploy.sh script itself is intentionally not committed (it embeds local workstation state — SSH key path, host alias). deploy.sh.example is the template.

The script:

1. Builds the frontend (npm install && npm run build)
2. Bundles the frontend into backend/src/main/resources/static/
3. Builds the backend jar (./gradlew bootJar)
4. On the server, rotates app.jar → app.jar.previous (one-step rollback)
5. Uploads the new jar as app.jar.new and atomically swaps it into place
6. systemctl restart benemap and waits up to 20s for the service to come back up
7. Health-checks http://127.0.0.1:48100/ over the local backend port

Configuration on the server lives in ~/services/benemap/.env (SMTP credentials, base URL) and is sourced via systemd's EnvironmentFile=. Never commit .env.

The pre-2026-09-11 Uberspace deploy script is preserved at deploy.uberspace.sh.disabled for historical reference; do not run it.

Notes

• No HTML templates in backend — frontend Svelte SPA handles UI
• Modular frontend allows multiple pages/components
• Works best with JS enabled; Svelte SPA will be blank if JS is blocked

---

Roadmap / Most important TODOs

Full backlog lives in orga/board.md. Before a public beta, the priorities are:

• Schritt-für-Schritt-Anleitung für Anbieter — the target audience (Vereine, Vermittlungsstellen) skews older and less app-experienced

License

AGPLv3 — see LICENSE. If you run a modified version of Benemap as a network service, you must make the source of your version available to its users.

Contributing

See CONTRIBUTING.md for how to get set up and submit changes.