{"id":36964068,"url":"https://github.com/ghmer/rego-adventure","last_synced_at":"2026-04-03T22:03:47.791Z","repository":{"id":328518026,"uuid":"1113361648","full_name":"ghmer/rego-adventure","owner":"ghmer","description":"An interactive learning platform for mastering Policy-Based Access Control (PBAC) using Open Policy Agent (OPA) and Rego policy language through themed quest-based challenges.","archived":false,"fork":false,"pushed_at":"2026-03-21T06:23:00.000Z","size":1574,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-21T22:25:04.467Z","etag":null,"topics":["adventure","open-policy-agent","rego"],"latest_commit_sha":null,"homepage":"https://regoadventure.r5i.xyz","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ghmer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":"COPYRIGHT.md","agents":null,"dco":null,"cla":null}},"created_at":"2025-12-09T21:51:38.000Z","updated_at":"2026-03-14T14:15:10.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ghmer/rego-adventure","commit_stats":null,"previous_names":["ghmer/rego-adventure"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/ghmer/rego-adventure","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ghmer%2Frego-adventure","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ghmer%2Frego-adventure/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ghmer%2Frego-adventure/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ghmer%2Frego-adventure/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ghmer","download_url":"https://codeload.github.com/ghmer/rego-adventure/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ghmer%2Frego-adventure/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31379453,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T21:40:47.592Z","status":"ssl_error","status_checked_at":"2026-04-03T21:40:05.436Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adventure","open-policy-agent","rego"],"created_at":"2026-01-13T19:16:36.742Z","updated_at":"2026-04-03T22:03:47.786Z","avatar_url":"https://github.com/ghmer.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Rego Adventure\n\nAn interactive learning platform for mastering Policy-Based Access Control (PBAC) using Open Policy Agent (OPA) and Rego policy language through themed quest-based challenges.\n\n## example deployment\n\nA deployment with custom quests exists at [https://regoadventure.r5i.xyz](https://regoadventure.r5i.xyz).\n\nUse the following credentials:\n- user: rego\n- pass: adventure\n\n### Gallery of custom adventures\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"docu/images/screenshot_ui_1.jpg\"\u003e\u003cimg src=\"docu/images/screenshot_ui_1.jpg\" alt=\"Screenshot 1\" width=\"400\"\u003e\u003c/a\u003e\n  \u003ca href=\"docu/images/screenshot_ui_2.jpg\"\u003e\u003cimg src=\"docu/images/screenshot_ui_2.jpg\" alt=\"Screenshot 2\" width=\"400\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"docu/images/screenshot_ui_3.jpg\"\u003e\u003cimg src=\"docu/images/screenshot_ui_3.jpg\" alt=\"Screenshot 3\" width=\"400\"\u003e\u003c/a\u003e\n  \u003ca href=\"docu/images/screenshot_ui_4.jpg\"\u003e\u003cimg src=\"docu/images/screenshot_ui_4.jpg\" alt=\"Screenshot 4\" width=\"400\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n## Architecture\n\nThe system breaks down into two main parts. A Go backend handles HTTP requests, quest loading, policy verification through OPA, and optional JWT authentication. The JavaScript frontend provides the interactive adventure interface with dynamic theming based on quest pack genre.\n\n### Backend (Go)\n\n- HTTP Server: gin-gonic based REST API\n- Quest System: Dynamic quest pack loading from JSON files\n- Policy Verification: OPA integration for Rego policy evaluation against test cases\n- Authentication: Optional OIDC/JWT authentication with JWKS validation\n\n**Key Components:**\n- [`main.go`](main.go:1) - Application entry point and initialization\n- [`backend/http/`](backend/http/) - HTTP server, routing, and middleware\n- [`backend/quest/`](backend/quest/) - Quest models, repository, and verification logic\n- [`backend/config/`](backend/config/) - Configuration management\n\n### Frontend (JavaScript)\n\n- Adventure Interface: Single-page application for quest progression\n- Theme System: Dynamic styling based on quest pack genre\n\n**Structure:**\n- [`frontend/adventure/`](frontend/adventure/) - Main game interface\n- [`frontend/quests/`](frontend/quests/) - Quest pack definitions (JSON) and assets\n\n## Prerequisites\n\nYou'll need Go 1.25 or higher. Docker is optional but useful for containerized deployment, and Kubernetes if you are going that route.\n\n## Installation\n\n### Local Development\n\n1. Clone the repository\n2. Install dependencies:\n   ```bash\n   go mod download\n   ```\n\n3. Set required environment variables:\n   ```bash\n   export DOMAIN=\"http://localhost:8080\"\n   export PORT=\"8080\"\n   ```\n\n4. Optional authentication configuration:\n   ```bash\n   export AUTH_ENABLED=\"true\"\n   export AUTH_ISSUER=\"https://your-issuer.com\"\n   export AUTH_DISCOVERY_URL=\"https://your-issuer.com/.well-known/openid-configuration\"\n   export AUTH_CLIENT_ID=\"your-client-id\"\n   export AUTH_AUDIENCE=\"your-audience\"\n   ```\n\n5. Run the application:\n   ```bash\n   go run main.go\n   ```\n\n## Running the Application\n\n### Development Mode\n\n```bash\ngo run main.go\n```\n\nAccess the application at `http://localhost:8080`\n\n### Production Build\n\n```bash\ngo build -ldflags \"-s -w\" -trimpath -o rego-adventure .\n./rego-adventure\n```\n\n### Docker\n\nBuild the image:\n```bash\ndocker build -t rego-adventure .\n```\n\nRun the container:\n```bash\ndocker run -p 8080:8080 \\\n  -e DOMAIN=\"http://localhost:8080\" -e PORT=\"8080\" \\\n  rego-adventure\n```\n\nSee [`docker-compose.yml`](docu/deploy/docker/docker-compose.yml) for Docker Compose configuration.\n\n### Kubernetes\n\nDeploy using the provided manifests.\n\nEither:\n```bash\nkubectl apply -k docu/deploy/k8s\n```\n\nOr if you prefer to apply files individually:\n```bash\nkubectl apply -f docu/deploy/k8s/configmap.yaml\nkubectl apply -f docu/deploy/k8s/deployment.yaml\nkubectl apply -f docu/deploy/k8s/service.yaml\nkubectl apply -f docu/deploy/k8s/ingress.yaml\n```\n\nConfiguration is managed via ConfigMap. Update [`configmap.yaml`](docu/deploy/k8s/configmap.yaml) with your environment-specific values.\n\n## Project Structure\n\n```\n.\n├── main.go                # Application entry point\n├── cmd/\n│   └── assetgen/          # Quest pack asset generator\n├── backend/\n│   ├── config/            # Configuration management\n│   ├── http/              # HTTP server and routing\n│   └── quest/             # Quest system logic\n├── frontend/\n│   ├── adventure/         # Main game interface\n│   ├── quests/            # Quest packs (JSON + assets)\n│   └── shared/            # Shared CSS, fonts, and resources\n├── docu/\n│   └── deploy/            # Deployment configurations\n│       ├── docker/        # Docker Compose\n│       └── k8s/           # Kubernetes manifests\n├── Dockerfile             # Multi-stage container build\n└── go.mod                 # Go dependencies\n```\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `DOMAIN` | Yes | - | Application domain (e.g., `https://example.com`) |\n| `PORT` | No | `8080` | HTTP server port |\n| `AUTH_ENABLED` | No | `false` | Enable OIDC authentication |\n| `AUTH_ISSUER` | Conditional | - | OIDC issuer URL (required if auth enabled) |\n| `AUTH_DISCOVERY_URL` | Conditional | - | OIDC discovery endpoint (required if auth enabled) |\n| `AUTH_CLIENT_ID` | Conditional | - | OIDC client ID (required if auth enabled) |\n| `AUTH_AUDIENCE` | Conditional | - | JWT audience claim (required if auth enabled) |\n| `TRUSTED_PROXIES` | No | - | Comma-separated CIDR ranges for trusted proxies |\n| `SHOW_IMPRESSUM` | No | `false` | Enable impressum/legal notice page link in footer |\n\n\u003e **Note:** When deploying behind a proxy or load balancer (e.g., nginx, Kubernetes ingress, cloud load balancer), it is important to set `TRUSTED_PROXIES` to ensure accurate client IP detection. Without this configuration, the application will see the proxy's IP address instead of the actual client IP. Set this to the CIDR range(s) of your trusted proxy infrastructure (e.g., `TRUSTED_PROXIES=\"10.0.0.0/8,172.16.0.0/12\"`).\n\n### Authentication\n\nThe application uses the **OIDC/OAuth2 Authorization Code Flow** if `AUTH_ENABLED` is set to `true`. More information can be found in [AUTHENTICATION.md](AUTHENTICATION.md).\n\n### Impressum / Legal Notice Configuration\n\nThe application includes an optional impressum (legal notice) page that can be enabled for deployments requiring legal compliance (e.g., German TMG requirements).\n\n**Enable the Impressum Page:**\n\nSet the `SHOW_IMPRESSUM` environment variable to `true`:\n```bash\nexport SHOW_IMPRESSUM=\"true\"\n```\n\n**Customize the Impressum Content:**\n\nThe default impressum page at [`frontend/adventure/impressum.html`](frontend/adventure/impressum.html) is a template with placeholder content. You **must** customize it with your actual legal information before deploying to production.\n\n**Docker Deployment:**\n\nOverride the impressum file using a volume mount in your `docker-compose.yml`:\n```yaml\nservices:\n  rego-adventure:\n    # ... other configuration ...\n    environment:\n      - SHOW_IMPRESSUM=true\n    volumes:\n      # Mount your custom impressum file\n      - ./custom-impressum.html:/app/frontend/adventure/impressum.html:ro\n```\n\nCreate your `custom-impressum.html` file with your actual legal information, then start the container.\n\n**Kubernetes Deployment:**\n\n**Option 1: Using a ConfigMap (Recommended)**\n\n1. Create a ConfigMap with your custom impressum content:\n```bash\nkubectl create configmap impressum-html --from-file=impressum.html=./custom-impressum.html\n```\n\n2. Update your deployment to mount the ConfigMap:\n```yaml\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: rego-adventure\nspec:\n  template:\n    spec:\n      containers:\n        - name: rego-adventure\n          env:\n            - name: SHOW_IMPRESSUM\n              value: \"true\"\n          volumeMounts:\n            - name: impressum-volume\n              mountPath: /app/frontend/adventure/impressum.html\n              subPath: impressum.html\n              readOnly: true\n      volumes:\n        - name: impressum-volume\n          configMap:\n            name: impressum-html\n```\n\n**Option 2: Using a PersistentVolume**\n\nMount a PersistentVolume containing your custom impressum.html file to `/app/frontend/adventure/impressum.html`.\n\n**Important Notes:**\n- The impressum page is disabled by default (`SHOW_IMPRESSUM=false`)\n- When enabled, a link appears in the application footer\n- Always replace placeholder content with actual legal information\n- Ensure compliance with your local legal requirements (TMG, GDPR, etc.)\n\n## Quest Packs\n\nQuest packs are defined in JSON format in a dedicated folder under [`frontend/quests/`](frontend/quests/) (for example: `frontend/quests/my-quest-pack`). Each pack contains:\n\n- Metadata (title, description, genre)\n- Prologue and epilogue narratives\n- Quest definitions with test cases\n- Theme-specific assets (images, audio, styles)\n\n### Asset Generator\n\nThe asset generator tool creates new quest pack scaffolding with placeholder assets and configuration files.\n\n**Location:** [`cmd/assetgen/`](cmd/assetgen/)\n\n**Usage:**\n```bash\ngo run cmd/assetgen/main.go -theme \u003ctheme-name\u003e -output \u003coutput-directory\u003e\n```\n\n**Example:**\n```bash\ngo run cmd/assetgen/main.go -theme western -output frontend/quests\n\n# creates a folder \"western\" below \"frontend/quests\"\n```\n\n**Generated Files:**\n- `quests.json` - Quest pack definition with 3 sample quests\n- `theme.css` - Theme-specific CSS variables and overrides\n- `custom.css` - Template for theme-specific visual effects\n- `README.md` - Quest pack customization guide\n- `assets/` - Directory containing placeholder images:\n  - `bg-adventure.jpg` (1920x1080) - Background image\n  - `hero-avatar.png` (128x128) - Player avatar\n  - `npc-questgiver.png` (128x128) - Quest giver avatar\n  - `icon-success.png` (128x128) - Success icon\n  - `icon-failure.png` (128x128) - Failure icon\n  - `perfect_score.png` (512x512) - Perfect score image\n  - `bg-music.m4a` - Empty placeholder for background music\n\nAll generated images are solid color placeholders. Replace with theme-appropriate artwork before deployment.\n\n### Mounting Quest Packs\n\nCustom quest packs can be added to the application by mounting them into the container. The target directory is `/app/frontend/quests/`.\n\n**Docker:**\n\nMount your local quest pack folder to a subdirectory within `frontend/quests`:\n```bash\ndocker run -v ./my-pack:/app/frontend/quests/my-pack ...\n```\n\n**Docker Compose:**\n\nMount your local quest pack folder using the `volumes` configuration:\n```yaml\nvolumes:\n  - ./my-pack:/app/frontend/quests/my-pack\n```\n\n**Kubernetes:**\n\nMount a volume containing your quest pack structure to the same path:\n```yaml\nvolumeMounts:\n  - name: my-quest-pack\n    mountPath: /app/frontend/quests/my-pack\n```\n\n## Quest Editor\n\nA browser-based visual editor for creating and modifying quest packs. The editor provides a complete interface for managing all aspects of quest pack development without requiring manual JSON editing.\n\n**Location:** [`docu/quest-editor/`](docu/quest-editor/)\n\n**How to Use:**\n1. Open [`index.html`](docu/quest-editor/index.html) in a web browser\n2. Click \"Load Quest File\" and select a `quests.json` file from any quest pack\n3. Edit quest content using the visual interface\n4. Click \"Save\" to download the modified `quests.json` file\n\nFor more complete documentation, check out [`README_EDITOR.md`](README_EDITOR.md).\n\n## deployment\n\nThe application is designed for cloud-native deployment with:\n\n- Read-only root filesystem support\n- Non-root user execution (UID 10001)\n- Health check endpoints (`/health`)\n\nRefer to:\n\n- [`Dockerfile`](Dockerfile) for container build configuration\n- [`docker-compose.yml`](docu/deploy/docker/docker-compose.yml) for Docker-based setups, and\n- [`kustomization.yaml`](docu/deploy/k8s/kustomization.yaml) for Kubernetes deployments\n\n### Quest Packs Deployment\n\nLocally, a quest pack must go in the `frontend/quests` folder.\n\nFor Kubernetes or Docker Compose deployments, you can mount them there too.\n\n## License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.\n\n## Copyright\n\nCopyright 2025 Mario Enrico Ragucci - see [COPYRIGHT.md](COPYRIGHT.md) for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fghmer%2Frego-adventure","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fghmer%2Frego-adventure","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fghmer%2Frego-adventure/lists"}