🌴 Offly — Time Off Manager

Modern absence & time off management. Simple, fast, self-hosted.

---

📖 New here? Check out the Quick Start Guide to get up and running in 5 minutes!

✨ Features

Feature	Description
📅 Calendar Grid	Visual month-by-month absence grid per user & team
👥 Team Management	Organize users into teams with availability tracking
🏖️ Absence Types	Full day, morning only, afternoon only
🌍 Public Holidays	Per-country holiday management
🔍 Quick Search	Instant search across users and teams
🌙 Dark Mode	Full light/dark theme support
📊 Presence View	Real-time daily attendance overview
📤 Export	CSV and PDF export of absence reports
🔐 SSO / OIDC	Optional SSO authentication via Dex (PKCE flow)
🛡️ RBAC	Role-based access control (admin / user)
🚀 Self-hosted	Single Docker image — no external services required

📸 Screenshots

Calendar View	Teams

Users	Holidays

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│ Browser (React) │
│ TypeScript · Tailwind CSS · Vite 8 │
└───────────────────────┬─────────────────────────────────┘
│ HTTP / REST
┌───────────────────────▼─────────────────────────────────┐
│ Go Backend │
│ gRPC · gRPC-Gateway · Protocol Buffers │
├─────────────────┬───────────────────────────────────────┤
│ SQLite (default) │ MongoDB (optional) │
└───────────────────────┴─────────────────────────────────┘

The single Docker image embeds both the Go binary and the compiled React SPA. The backend serves the frontend static files and provides the REST/gRPC API.

🛠️ Tech Stack

Layer	Technology
Backend	Go 1.26, gRPC, gRPC-Gateway, Protocol Buffers
Frontend	React 18, TypeScript 5, Tailwind CSS 3, Vite 8
Database	SQLite (default) · MongoDB (optional)
Auth	Dex (OIDC/PKCE), JWT, JWKS
Container	Docker (multi-stage, Alpine)
Orchestration	Kubernetes · Helm · Skaffold
CI/CD	GitHub Actions (SHA-pinned)

📋 Prerequisites

Tool	Version	Purpose
Go	1.26+	Backend
Node.js	24+	Frontend
Task	latest	Task runner
Buf	latest	Protobuf tooling
Docker	latest	Containers

🚀 Quick Start

Option 1 — Docker Compose (recommended)

docker-compose up -d

The application is available at http://localhost:8080

Option 2 — Local development

# Clone
git clone https://github.com/BananaOps/offly.git &&cd offly
# Install all dependencies and generate protobuf code
task setup
# Start the app (backend + frontend with hot reload)
task dev

Service	URL
Web UI	http://localhost:3000
REST API	http://localhost:8080/api/v1
Swagger UI	http://localhost:8080/docs
gRPC	localhost:50051

Seed test data

# Requires k6 — see k6-README.md
k6 run k6-seed-data.js

Creates 5 departments, 10 teams, 12 users, 29 public holidays, and random absences.

🐳 Docker

# Pull & run (in-memory storage — no DB required)
docker run -p 8080:8080 bananaops/offly:latest
# With persistent SQLite
docker run -p 8080:8080 \
-v $(pwd)/data:/app/data \
bananaops/offly:latest
# With MongoDB
docker run -p 8080:8080 \
-e STORAGE_TYPE=mongodb \
-e MONGO_URI=mongodb://host.docker.internal:27017 \
bananaops/offly:latest

See DOCKER.md for the full deployment guide.

☸️ Kubernetes (Helm)

# Add the chart repository
helm repo add offly https://bananaops.github.io/offly
helm repo update
# Install
helm install offly offly/offly
# Install a specific version
helm install offly offly/offly --version 0.1.0
# Upgrade
helm upgrade offly offly/offly

⚙️ Environment Variables

Variable	Description	Default
STORAGE_TYPE	sqlite or mongodb	sqlite
SQLITE_DB_PATH	SQLite database path	/app/data/offly.db
MONGO_URI	MongoDB connection string	mongodb://localhost:27017
HTTP_PORT	HTTP server port	8080
GRPC_PORT	gRPC server port	50051
AUTH_ENABLED	Enable SSO authentication	false
AUTH_ISSUER_URL	OIDC issuer URL	—
AUTH_CLIENT_ID	OIDC client ID	—

🔐 SSO Authentication

Offly supports optional SSO via Dex (OIDC/PKCE flow).

Browser ──PKCE──▶ Dex ──ID Token──▶ Backend ──JWT verify──▶ SQLite

Role	Permissions
admin	Full access — users, teams, holidays, absences
user	Read all · Edit own profile & absences only

See SSO-README.md for the full configuration guide.

🔌 API

REST (port 8080)

Interactive documentation available at http://localhost:8080/docs

Method	Endpoint	Description
GET	/api/v1/health	Health check
GET/POST	/api/v1/users	List / create users
GET/PUT/DELETE	/api/v1/users/{id}	Get / update / delete user
GET/POST	/api/v1/teams	List / create teams
GET/POST	/api/v1/absences	List / create absences
PUT/DELETE	/api/v1/absences/{id}	Update / delete absence
GET/POST	/api/v1/holidays	List / create public holidays
GET	/api/v1/auth/config	SSO configuration
POST	/api/v1/auth/ensure-user	Auto-provision SSO user

gRPC (port 50051)

Services: AbsenceService · UserService · OrganizationService · HolidayService

🧰 Task Commands

task setup # Install deps + generate protobuf code
task dev # Start backend + frontend (hot reload)
task build # Build the full application
task test# Run all tests
task lint # Lint backend + frontend
task format # Format backend + frontend
task proto # Regenerate protobuf code
task proto:lint # Lint protobuf definitions
task mongo:start # Start MongoDB in Docker
task mongo:stop # Stop MongoDB
task pre-commit # Format + lint + test (run before committing)
task clean # Remove generated files

📁 Project Structure

offly/
├── backend/
│ ├── cmd/server/ # Server entry point
│ ├── internal/
│ │ ├── auth/ # OIDC, JWT, RBAC middleware
│ │ ├── service/ # gRPC service implementations
│ │ └── storage/ # SQLite + MongoDB adapters
│ └── proto/ # Protocol Buffer definitions
├── frontend/
│ └── src/
│ ├── components/ # React components
│ │ ├── AbsenceGrid # Main calendar grid
│ │ ├── PresenceView # Daily attendance view
│ │ ├── UserManagement
│ │ ├── TeamManagement
│ │ └── HolidayManagement
│ ├── api.ts # REST API client
│ ├── auth.ts # PKCE / JWT helpers
│ └── types.ts # TypeScript types
├── helm/offly/ # Helm chart for Kubernetes
├── dex/ # Dex OIDC provider (dev/test)
├── Dockerfile # Multi-stage build (frontend + backend)
├── docker-compose.yml # Local stack
├── Taskfile.yml # Task automation
└── k6-seed-data.js # Test data generator

🤝 Contributing

Contributions are welcome! We follow Conventional Commits:

git commit -m "feat: add new absence type filter"
git commit -m "fix: correct date calculation in calendar"
git commit -m "docs: update API reference"

Types: feat · fix · docs · chore · ci · refactor · perf · test

Releases are automated via Release Please.

🐛 Troubleshooting

MongoDB won't start

task mongo:stop && task mongo:start

Protobuf compilation errors

task install:backend
task proto:lint # Check for syntax errors
task proto # Regenerate

Frontend dependency issues

cd frontend && rm -rf node_modules package-lock.json && npm install

SSO / Dex issues

See SSO-README.md for detailed troubleshooting steps.

📄 License

Released under the MIT License — © BananaOps

---

Documentation · Issues · Discussions · Docker Hub

Made with ❤️ by BananaOps