OSShip

Live demo → https://osship.app

Project presentation

Video walkthrough of OSShip — what the platform does, how it works, and how the pieces fit together:

Watch on Tella → OSShip presentation

Backup - Video presentation

About

OSShip is an open-source mentorship platform that connects students with OSS maintainers through paid, structured mentorship on real projects. Students browse listings, enroll in multi-week slots, join live video sessions, and build verifiable portfolio evidence. Mentors publish listings with their own pricing and schedule; admins review mentor applications and oversee the public payout ledger.

The platform is built as a microservices monorepo orchestrated with Docker Compose:

Layer	Stack
Frontend	Next.js UI behind Nginx
API	Go gateway with JWT auth, rate limiting, and Swagger docs
Services	Auth, users, listings, sessions, mentors, notifications (Go); payments and metrics (Rust)
Data	PostgreSQL, Redis, Kafka
Integrations	Stripe Connect (payments), Jitsi (live sessions), Resend (email), GitHub OAuth
Observability	Prometheus, Grafana, optional Sentry

Application code lives in Git submodules; this repository provides orchestration, migrations, and infrastructure config.

Run locally

Prerequisites

Tool	Purpose
Git	Clone the meta-repo and its submodules
Docker Engine + Compose v2	Run the full stack (docker compose)
Make	Project shortcuts in Makefile
Go	Migrations, seed data, Swagger generation, and tests
curl	Health-check script

Node.js is only required if you run the UI outside Docker; the default stack builds it inside the ui image.

1. Clone

git clone --recurse-submodules git@github.com:OSShip/osship.git
cd osship

If you already cloned without submodules:

git submodule update --init --recursive

2. Configure environment

cp .env.example .env

Update .env only for integrations you want to exercise locally:

• JWT_SECRET — change for any non-throwaway environment.
• GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, GITHUB_TOKEN — GitHub OAuth and profile workflows.
• STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET — real Stripe payment flows.
• RESEND_API_KEY — real email delivery.
• SENTRY_DSN, NEXT_PUBLIC_SENTRY_DSN — optional; empty values disable reporting.

3. Start the stack

make up

Nginx exposes the app on port 3000 (mapped to port 80 inside the container).

4. Seed demo data (optional)

make seed

Demo accounts (password: password123):

Role	Email
Student	student@osship.local
Mentor	mentor@osship.local
Admin	admin@osship.local

5. Verify

./scripts/health-check.sh http://localhost:3000

URL	Description
http://localhost:3000	Web app
http://localhost:3000/api/v1/health	Gateway health
http://127.0.0.1:3030	Grafana (localhost only; credentials in .env)

Swagger UI is available only in development (make dev sets ENABLE_SWAGGER=true): http://localhost:8080/api/docs/

Development mode

To expose individual service ports on the host (UI on :3000, gateway on :8080, Postgres on :5432, etc.):

make dev

Common commands:

make logs # Follow Docker Compose logs
make recreate # Rebuild and recreate services
make dev-recreate # Rebuild the development stack
make migrate # Re-run database migrations
make down # Stop the default stack
make dev-down # Stop the development stack

If port 3000 is already in use, stop the conflicting process or change the nginx port mapping in docker-compose.yml.

Submodules

Path	Repository	Description
ui/	OSShip/ui	Next.js frontend
utils/	OSShip/utils	Shared Go libraries
services/auth/	OSShip/auth	Authentication
services/gateway/	OSShip/gateway	API gateway
services/listings/	OSShip/listings	Mentorship listings
services/users/	OSShip/users	User profiles
services/sessions/	OSShip/sessions	Mentorship sessions
services/mentors/	OSShip/mentors	Mentor applications
services/notifications/	OSShip/notifications	Email notifications
services/payments/	OSShip/payments	Stripe payments
services/metrics/	OSShip/metrics	Event metrics

API documentation

Swagger UI is served by the gateway in development only (ENABLE_SWAGGER=true via docker-compose.dev.yml):

URL	Description
http://localhost:8080/api/docs/	Swagger UI (dev only)
http://localhost:8080/api/docs/doc.json	OpenAPI spec (dev only)

After changing endpoint annotations in services/gateway/internal/apidoc/:

make swagger

Observability

Layer	Tool	Local access
Metrics	Prometheus + Grafana	http://127.0.0.1:3030 (SSH tunnel on remote hosts)
Errors	Sentry	Set SENTRY_DSN and NEXT_PUBLIC_SENTRY_DSN in .env

Production deploy

./scripts/deploy.sh

CI/CD is configured via Jenkins (deploy/Jenkinsfile).

License

MIT — see LICENSE.