{"id":45465376,"url":"https://github.com/sethbacon/terraform-registry-backend","last_synced_at":"2026-06-07T07:04:54.524Z","repository":{"id":342393052,"uuid":"1172365410","full_name":"sethbacon/terraform-registry-backend","owner":"sethbacon","description":"Private Terraform registry implementing the HashiCorp module, provider, and network mirror protocols","archived":false,"fork":false,"pushed_at":"2026-05-04T15:27:43.000Z","size":2690,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-04T17:26:59.237Z","etag":null,"topics":["gin","go","infrastructure-as-code","postgresql","private-registry","terraform","terraform-registry"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sethbacon.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-04T08:19:12.000Z","updated_at":"2026-05-04T15:27:36.000Z","dependencies_parsed_at":null,"dependency_job_id":"3b389f5f-a6c5-456d-ad64-656f4be64c27","html_url":"https://github.com/sethbacon/terraform-registry-backend","commit_stats":null,"previous_names":["sethbacon/terraform-registry-backend"],"tags_count":82,"template":false,"template_full_name":null,"purl":"pkg:github/sethbacon/terraform-registry-backend","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sethbacon%2Fterraform-registry-backend","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sethbacon%2Fterraform-registry-backend/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sethbacon%2Fterraform-registry-backend/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sethbacon%2Fterraform-registry-backend/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sethbacon","download_url":"https://codeload.github.com/sethbacon/terraform-registry-backend/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sethbacon%2Fterraform-registry-backend/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32723647,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-07T02:14:30.463Z","status":"ssl_error","status_checked_at":"2026-05-07T02:14:29.405Z","response_time":62,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6: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":["gin","go","infrastructure-as-code","postgresql","private-registry","terraform","terraform-registry"],"created_at":"2026-02-22T09:23:10.139Z","updated_at":"2026-05-07T05:01:39.462Z","avatar_url":"https://github.com/sethbacon.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- markdownlint-disable MD013 MD024 --\u003e\n# Enterprise Terraform Registry — Backend\n\nA fully-featured, enterprise-grade Terraform registry implementing all three HashiCorp protocols with multi-tenancy support.\n\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)\n[![Go Version](https://img.shields.io/badge/Go-1.26+-00ADD8?logo=go)](https://go.dev/)\n[![Coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/sethbacon/59239e8575b4f784f875647e2b344b41/raw/coverage.json)](https://github.com/sethbacon/terraform-registry-backend/actions/workflows/ci.yml)\n\nThis repository contains the backend API, database migrations, and deployment infrastructure for the Enterprise Terraform Registry. The frontend UI is a separate React SPA: **[terraform-registry-frontend](https://github.com/sethbacon/terraform-registry-frontend)**.\n\n## Features\n\n### Terraform Protocol Support\n\n- **Module Registry Protocol** — Complete implementation for hosting and discovering Terraform modules\n- **Provider Registry Protocol** — Full provider hosting with platform-specific binaries\n- **Provider Network Mirror Protocol** — Efficient provider mirroring and caching\n\n### Authentication \u0026 Authorization\n\n- **API Key Authentication** — Secure token-based access with scoped permissions\n- **OIDC Integration** — Generic OIDC provider support for SSO\n- **Azure AD / Entra ID** — Native Azure Active Directory integration\n- **Role-Based Access Control (RBAC)** — Fine-grained permissions with organization roles\n\n### Multi-Tenancy\n\n- **Organization Management** — Isolated organization namespaces for teams and projects\n- **User Management** — Comprehensive user administration\n- **Organization Membership** — Role-based team collaboration (viewer, publisher, devops, user_manager, auditor, admin)\n- **Configurable Modes** — Single-tenant or multi-tenant deployment\n\n### Module Source Control (SCM) Integration\n\n- **GitHub Integration** — Connect modules to GitHub repositories with OAuth\n- **Azure DevOps Integration** — Native support for Azure Repos\n- **GitLab Integration** — Full GitLab repository support\n- **Bitbucket Data Center** — Self-hosted Bitbucket with PAT authentication\n- **Webhook Support** — Automatic publishing on repository events\n\n### Storage Backends\n\n- **Local Filesystem** — Direct file serving for development and simple deployments\n- **Azure Blob Storage** — Cloud storage with SAS tokens, CDN URLs, and flexible access tiers\n- **AWS S3 / S3-Compatible** — AWS S3, MinIO, and DigitalOcean Spaces with presigned URLs\n- **Google Cloud Storage** — Native GCS integration with signed URLs and resumable uploads\n- **Pluggable Architecture** — Extensible storage interface for adding new backends\n\n### Deployment Options\n\nDocker Compose, Kubernetes (Kustomize and Helm), Azure Container Apps, AWS ECS\nFargate, Google Cloud Run, standalone binary + systemd, and full Terraform IaC\nfor all three major clouds. See the [Deployment Guide](docs/deployment.md) for\nthe full matrix, recommended targets, and step-by-step instructions.\n\n### Terraform Binary Mirror\n\n- **Multi-Config Mirror** — Multiple named mirror configs coexist; independently mirror HashiCorp Terraform, OpenTofu, or custom upstream sources side-by-side\n- **Tool Support** — `terraform`, `opentofu`, and `custom` tool types with per-config upstream URL\n- **Supply-Chain Security** — GPG signature verification against the embedded HashiCorp release key (OpenTofu support configurable)\n- **Platform Filtering** — Optionally restrict which `os/arch` combinations are downloaded and served\n- **Public Download API** — Unauthenticated endpoints at `/terraform/binaries/:name/versions/…` compatible with Terraform's [network mirror protocol](https://developer.hashicorp.com/terraform/internals/provider-network-mirror-protocol)\n- **Prometheus Metric** — `terraform_binary_downloads_total` counter with `{version, os, arch}` labels\n\n### Module Security Scanning\n\n- **Automatic Scanning** — Every uploaded module version is automatically queued for a security scan\n- **Multiple Scanner Backends** — Trivy (recommended), Checkov, Terrascan, Snyk, or a custom binary\n- **Structured Results** — Severity counts (Critical/High/Medium/Low) and raw output stored per version\n- **Supply-Chain Protection** — Optional binary version pinning rejects mismatched scanner executables\n- **Module Documentation Extraction** — Inputs, outputs, provider requirements, and Terraform version constraints automatically extracted at upload time\n\n### Observability \u0026 CI/CD\n\n- **Prometheus Metrics** — Eleven named application metrics on a dedicated scrape port (default 9090)\n- **Structured Logging** — stdlib `slog` with JSON (production) and text (development) formats\n- **pprof Profiling** — Opt-in profiling server on a configurable port\n- **GitHub Actions CI/CD** — Build, vet, race-detector tests, gosec security scan, Docker build, multi-platform releases\n- **Bi-weekly Dependabot** — Automated Go module and Actions dependency updates\n\n## Tech Stack\n\n| Concern         | Technology                                                  |\n| --------------- | ----------------------------------------------------------- |\n| Language        | Go 1.26                                                     |\n| HTTP framework  | Gin                                                         |\n| Database        | PostgreSQL 14+ (16 recommended)                             |\n| Migrations      | `golang-migrate` (file-based, immutable numbered pairs)     |\n| Auth            | JWT (HS256), API keys, OIDC, Azure AD                       |\n| Storage         | Local FS, Azure Blob, AWS S3 (+compatible), Google Cloud    |\n| SCM             | GitHub, Azure DevOps, GitLab, Bitbucket Data Center         |\n| Observability   | Prometheus metrics, `slog` JSON logs, pprof                 |\n| API docs        | Swagger 2.0 (swag annotations) → served at `/swagger`       |\n| Build / release | GoReleaser, GitHub Actions, cosign keyless, SLSA, syft SBOM |\n\n## Architecture\n\n```txt\n┌────────────────────────────────────────────────────┐\n│              React TypeScript SPA                  │\n│  (see terraform-registry-frontend)                 │\n└──────────────────┬─────────────────────────────────┘\n                   │ REST API / Protocol Endpoints\n┌──────────────────▼─────────────────────────────────┐\n│              Go 1.26 Backend (Gin)                 │\n│  Modules API │ Providers API │ Mirror │ Admin      │\n│  Terraform Binary Mirror                           │\n│  Auth: JWT │ API Keys │ OIDC │ Azure AD │ RBAC     │\n│  SCM: GitHub │ Azure DevOps │ GitLab │ Bitbucket   │\n│  Storage: Local │ Azure Blob │ S3 │ GCS            │\n└──────────────────┬─────────────────────────────────┘\n                   │\n          ┌────────┴────────┐\n          │   PostgreSQL    │\n          └─────────────────┘\n```\n\n## Installation\n\n### Prerequisites\n\n- Go 1.26 or later\n- PostgreSQL 14 or later (16 recommended; used in Docker Compose and CI)\n- Docker \u0026 Docker Compose (for containerized deployment)\n\n### Quick Start with Docker Compose\n\n```bash\n# Clone the repository\ngit clone https://github.com/sethbacon/terraform-registry-backend.git\ncd terraform-registry-backend\n\n# Start all services (backend + postgres; frontend served separately)\ncd deployments\ndocker-compose up -d\n\n# Backend API: http://localhost:8080\n# PostgreSQL:  localhost:5432\n# Prometheus metrics: http://localhost:9090/metrics\n```\n\n\u003e For the web UI, see [terraform-registry-frontend](https://github.com/sethbacon/terraform-registry-frontend).\n\n### First-Run Setup\n\nOn first startup, the server prints a one-time **setup token** to the logs. Use this token to configure the registry through the web wizard at `/setup` or via the setup API. The wizard guides you through:\n\n1. OIDC provider configuration (authentication)\n2. Storage backend configuration (where modules/providers are stored)\n3. Initial admin user setup\n\nSee [Initial Setup Guide](docs/initial-setup.md) for full details, including headless/curl-based setup.\n\n### Manual Setup\n\n```bash\ncd backend\n\n# Install dependencies\ngo mod download\n\n# Set up configuration\ncp config.example.yaml config.yaml\n# Edit config.yaml with your settings\n\n# Run database migrations\ngo run cmd/server/main.go migrate up\n\n# Start the server\ngo run cmd/server/main.go serve\n```\n\n## Configuration\n\nAll configuration can be set via environment variables (prefix: `TFR_`) or YAML config file.\n\n```bash\n# Database\nexport TFR_DATABASE_HOST=localhost\nexport TFR_DATABASE_PORT=5432\nexport TFR_DATABASE_USER=registry\nexport TFR_DATABASE_PASSWORD=your_password\nexport TFR_DATABASE_NAME=terraform_registry\nexport TFR_DATABASE_SSL_MODE=disable\n\n# Server\nexport TFR_SERVER_PORT=8080\nexport TFR_SERVER_HOST=0.0.0.0\nexport TFR_SERVER_BASE_URL=http://localhost:8080\n\n# Storage (choose one: local | azure | s3 | gcs)\nexport TFR_STORAGE_DEFAULT_BACKEND=local\nexport TFR_STORAGE_LOCAL_BASE_PATH=/var/lib/terraform-registry\n\n# Authentication\nexport TFR_AUTH_API_KEYS_ENABLED=true\nexport TFR_AUTH_OIDC_ENABLED=false\nexport TFR_AUTH_AZURE_AD_ENABLED=false\n\n# Security\nexport TFR_JWT_SECRET=your_jwt_secret          # min 32 chars in production\nexport ENCRYPTION_KEY=your_32_byte_encryption_key\n```\n\nSee `backend/config.example.yaml` for a complete configuration reference.\nSee [Configuration Reference](docs/configuration.md) for detailed guidance.\n\n## Monitoring \u0026 Observability\n\nThe registry exposes Prometheus metrics on a dedicated port (default **9090**).\n\n```bash\n# View all metrics\ncurl -s http://localhost:9090/metrics\n\n# Check HTTP request rates\ncurl -s http://localhost:9090/metrics | grep '^http_requests_total'\n```\n\n### Prometheus + Grafana Stack\n\n```bash\ncd deployments\ndocker-compose --profile monitoring up -d\n# Prometheus UI: http://localhost:9091\n# Grafana:       http://localhost:3001  (admin / admin)\n```\n\nSee [Observability Reference](docs/observability.md) for Grafana dashboard setup and alert rules.\n\n## Usage with Terraform\n\n```hcl\nterraform {\n  required_providers {\n    mycloud = {\n      source  = \"registry.example.com/myorg/mycloud\"\n      version = \"~\u003e 1.0\"\n    }\n  }\n}\n\nmodule \"vpc\" {\n  source  = \"registry.example.com/myorg/vpc/aws\"\n  version = \"2.1.0\"\n}\n```\n\n### Publishing Modules\n\n```bash\ncurl -X POST https://registry.example.com/api/v1/modules \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -F \"file=@module.tar.gz\" \\\n  -F \"namespace=myorg\" \\\n  -F \"name=vpc\" \\\n  -F \"system=aws\" \\\n  -F \"version=1.0.0\"\n```\n\n### Publishing Providers\n\n```bash\ncurl -X POST https://registry.example.com/api/v1/providers \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -F \"file=@terraform-provider-mycloud_1.0.0_linux_amd64.zip\" \\\n  -F \"namespace=myorg\" \\\n  -F \"type=mycloud\" \\\n  -F \"version=1.0.0\" \\\n  -F \"os=linux\" \\\n  -F \"arch=amd64\" \\\n  -F \"gpg_public_key=@public_key.asc\"\n```\n\n## Development\n\n### Running Tests\n\n```bash\ncd backend\ngo test ./...\n```\n\n### Building\n\n```bash\ncd backend\ngo build -o terraform-registry cmd/server/main.go\n```\n\n## Documentation\n\n- [Getting Started](docs/getting-started.md) — Quick-start tutorial for new users\n- [Architecture](docs/architecture.md) — System design and component interactions\n- [Architecture Decision Records](docs/adr/) — Key design decisions and rationale\n- [API Reference](docs/api-reference.md) — API documentation guide\n- [API Migration Guide](docs/api-migration-guide.md) — Breaking changes and migration steps across releases\n- [Configuration Reference](docs/configuration.md) — All `TFR_*` environment variables\n- [Deployment Guide](docs/deployment.md) — Production deployment for all platforms\n- [Kubernetes Cloud Guides](docs/deployment/README.md) — AKS, EKS, and GKE deployment guides\n- [Capacity Planning](docs/capacity-planning.md) — Sizing guidance for production deployments\n- [Disaster Recovery](docs/disaster-recovery.md) — DR runbook and backup/restore procedures\n- [Observability Reference](docs/observability.md) — Prometheus metrics catalogue\n- [Troubleshooting](docs/troubleshooting.md) — Common issues and diagnostic tools\n- [Development Guide](docs/development.md) — Local development setup\n- [OIDC Configuration](docs/OIDC_CONFIGURATION.md) — SSO provider setup\n- [Module Security Scanning](docs/module-scanning.md) — Scanner setup (Trivy, Checkov, Terrascan, Snyk, custom)\n- [Module Documentation Extraction](docs/module-documentation.md) — Automatic extraction of inputs, outputs, and provider requirements\n- [Terraform CLI Configuration](docs/terraform-cli-configuration.md) — Configure the Terraform CLI to use this registry\n- [Releasing](RELEASING.md) — Release process and supply-chain verification\n- [Security](SECURITY.md) — Reporting vulnerabilities and supported versions\n- [Contributing](CONTRIBUTING.md) — How to contribute to this project\n- [Code of Conduct](CODE_OF_CONDUCT.md) — Community standards\n- [Changelog](CHANGELOG.md) — Version history and changes\n- [Frontend Repository](https://github.com/sethbacon/terraform-registry-frontend) — React SPA, accessibility, E2E tests\n\n## References\n\n- [Module Registry Protocol](https://developer.hashicorp.com/terraform/internals/module-registry-protocol)\n- [Provider Registry Protocol](https://developer.hashicorp.com/terraform/internals/provider-registry-protocol)\n- [Provider Network Mirror Protocol](https://developer.hashicorp.com/terraform/internals/provider-network-mirror-protocol)\n\n**Frontend:** [terraform-registry-frontend](https://github.com/sethbacon/terraform-registry-frontend)\n\n## Supply Chain Security\n\nEvery release includes build provenance attestations (via GitHub Artifact Attestations), SBOM generation, and Sigstore cosign signatures published to the [Rekor](https://rekor.sigstore.dev) public transparency log.\n\n### Verify a container image\n\n```bash\n# Verify the cosign signature and Sigstore identity\ncosign verify \\\n  --certificate-identity-regexp 'https://github\\.com/sethbacon/terraform-registry-backend/' \\\n  --certificate-oidc-issuer https://token.actions.githubusercontent.com \\\n  ghcr.io/sethbacon/terraform-registry-backend:latest\n\n# Search the Rekor transparency log for entries\nrekor-cli search --sha \u003cimage-digest\u003e\n```\n\n### Verify release binaries\n\n```bash\n# Verify the checksum file signature\ncosign verify-blob \\\n  --certificate-identity-regexp 'https://github\\.com/sethbacon/terraform-registry-backend/' \\\n  --certificate-oidc-issuer https://token.actions.githubusercontent.com \\\n  --signature checksums.txt.sig \\\n  --certificate checksums.txt.pem \\\n  checksums.txt\n\n# Verify build provenance\ngh attestation verify \u003cartifact\u003e --repo sethbacon/terraform-registry-backend\n```\n\n## Contributing\n\nContributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) before submitting pull requests. Key requirements:\n\n- `go fmt ./...` and `go vet ./...` must pass\n- New handlers require Swagger annotations\n- New features require documentation updates\n- Security issues must be reported privately (see CONTRIBUTING.md)\n\n## License\n\nThis project is licensed under the Apache License, Version 2.0 — see the [LICENSE](LICENSE) file for details.\n\n## Disclaimer\n\nThis software is provided **\"AS IS\"**, without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and non-infringement. In no event shall the authors or copyright holders be liable for any claim, damages, or other liability arising from the use of this software. See the [Apache 2.0 License](LICENSE) (Sections 7–8) for the full warranty disclaimer and limitation of liability.\n\n**Operational security is the responsibility of the deploying organization.** This includes, but is not limited to: securing the deployment environment, managing secrets and credentials, configuring TLS, enforcing network boundaries, rotating API keys, auditing access, keeping dependencies up to date, and validating the fitness of this software for your specific compliance and security requirements. The maintainers make no guarantees regarding the security posture of any deployment.\n\n## Acknowledgments\n\n- [HashiCorp Terraform](https://www.terraform.io/) - Module and Provider protocols\n- [Gin Web Framework](https://gin-gonic.com/) - Go HTTP framework\n\n### Trademark Notice\n\nHashiCorp, Terraform, and Vault are trademarks of HashiCorp, Inc. AWS and Amazon Web Services are trademarks of Amazon.com, Inc. or its affiliates. Microsoft Azure is a trademark of Microsoft Corporation. Google Cloud is a trademark of Google LLC. VMware and vSphere are trademarks of Broadcom Inc. Oracle and OCI are trademarks of Oracle Corporation. All other trademarks are the property of their respective owners.\n\nThis project is not affiliated with, endorsed by, or sponsored by any of the above-named organizations.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsethbacon%2Fterraform-registry-backend","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsethbacon%2Fterraform-registry-backend","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsethbacon%2Fterraform-registry-backend/lists"}