portkey

portkey is a lightweight, self‑hosted web portal written in Go that serves as a personal dashboard or startup page. At its core, the application exposes a single HTTP endpoint that renders a configurable list of links and optional custom pages. The entire user experience is driven by a single config.yml file, making it trivial to modify the UI without touching code. The application is intentionally minimal: no database layer, no authentication out of the box, and a small binary that can be run on any OS with Go support or via Docker.

Architecture & Technical Stack

• Language & Runtime: The codebase is pure Go (1.22+), leveraging the standard library’s net/http for routing and templating via html/template. The binary is compiled to a single static executable, which keeps the deployment footprint below 20 MiB (as reflected in Docker image size badges).
• Configuration: YAML is parsed with gopkg.in/yaml.v3. The config schema defines three top‑level sections: links, pages, and UI options (theme, search). The schema is validated at startup with a simple struct‑based check.
• Templating & Assets: Static assets (CSS, JavaScript, icons) live in the static/ directory and are embedded into the binary using Go’s embed package. This eliminates external file dependencies at runtime.
• Metrics: An optional /metrics endpoint exposes Prometheus counters for page views and request latency. The metrics package is lightweight (promhttp), allowing developers to hook into existing observability stacks.

Core Capabilities

• Link Collection: Each link entry supports a URL, title, icon (SVG or font‑awesome class), and optional tags for search filtering.
• Search: A client‑side JavaScript search bar filters links in real time based on configurable keyword matching (exact, prefix, fuzzy).
• Custom Pages: Developers can define small Markdown or HTML pages in the pages section, which are rendered via a templated layout. This feature is useful for embedding notes, calendars, or external widgets.
• Theming: Light/dark mode is toggled via CSS variables; the default theme can be set in the config.
• Extensibility: While portkey has no plugin API, its configuration-driven nature means developers can integrate it into larger systems by embedding the binary as a service or exposing its HTTP endpoints to other applications.

Deployment & Infrastructure

• Self‑Hosting: The application runs as a single binary, making it ideal for container orchestration (Docker, Kubernetes) or simple VM deployments. The Dockerfile uses a multi‑stage build to keep the final image lean.
• Scalability: Statelessness allows horizontal scaling behind a load balancer. Since there is no persistent state, any number of replicas can serve the same configuration file or mount a shared config via ConfigMap/Secret in Kubernetes.
• Resource Footprint: CPU usage is negligible (<5 % idle), and memory consumption stays under 50 MiB for typical workloads. This makes it suitable for low‑resource environments like Raspberry Pi or edge devices.
• Observability: The built‑in Prometheus metrics, combined with OpenTelemetry traces (optional), enable developers to monitor request latency and error rates without additional instrumentation.

Integration & Extensibility

• API Exposure: While portkey does not expose a REST API for CRUD operations, the /metrics endpoint and optional webhook hooks (configurable in config.yml) can be leveraged by external systems to trigger page updates or log analytics.
• Configuration CI/CD: The single config.yml file can be versioned in Git, allowing continuous deployment pipelines to push updated link collections or page content without rebuilding the binary.
• Custom Hooks: Advanced users can fork the project and add custom middleware or authentication layers (e.g., OAuth2) to secure the portal for internal teams.

Developer Experience

• Documentation: The README provides a clear, step‑by‑step guide. Configuration options are exhaustively documented in the config.yml example, and the codebase follows Go conventions with well‑named packages (internal, static).
• Community & Licensing: The project is AGPL‑3.0 licensed, encouraging open collaboration while ensuring that any derivative works remain open source. The repository has an active contributors list and a clear CONTRIBUTING guide.
• Testing: Unit tests cover configuration parsing, template rendering, and basic HTTP handlers. The CI pipeline (GitHub Actions) runs SonarCloud quality gates to enforce code standards.

Use Cases

Advantages Over Alternatives

• Zero‑Configuration Runtime: No database, no external services—everything runs from a single binary.
• Fast Startup & Low Resource Usage: Ideal for containers that need to spin up quickly and run in constrained environments.
• **Open