{"id":13505719,"url":"https://github.com/outsideris/citizen","last_synced_at":"2025-05-16T19:07:58.804Z","repository":{"id":38190332,"uuid":"111411206","full_name":"outsideris/citizen","owner":"outsideris","description":"A Private Terraform Module/Provider Registry","archived":false,"fork":false,"pushed_at":"2024-10-12T20:14:31.000Z","size":2793,"stargazers_count":639,"open_issues_count":45,"forks_count":87,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-04-14T13:58:29.005Z","etag":null,"topics":["registry","terraform","terraform-module","terraform-provider"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/outsideris.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":"outsideris"}},"created_at":"2017-11-20T13:02:59.000Z","updated_at":"2025-04-12T13:44:21.000Z","dependencies_parsed_at":"2024-01-03T02:27:32.359Z","dependency_job_id":"bd954d98-a82e-470f-96f3-2a6ccbfd7004","html_url":"https://github.com/outsideris/citizen","commit_stats":{"total_commits":584,"total_committers":14,"mean_commits":"41.714285714285715","dds":0.07534246575342463,"last_synced_commit":"6061a2531b9de45471a607c9d89536668838d1c9"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/outsideris%2Fcitizen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/outsideris%2Fcitizen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/outsideris%2Fcitizen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/outsideris%2Fcitizen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/outsideris","download_url":"https://codeload.github.com/outsideris/citizen/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254592395,"owners_count":22097013,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["registry","terraform","terraform-module","terraform-provider"],"created_at":"2024-08-01T00:01:12.213Z","updated_at":"2025-05-16T19:07:58.773Z","avatar_url":"https://github.com/outsideris.png","language":"JavaScript","funding_links":["https://github.com/sponsors/outsideris"],"categories":["Tools","Private Module Registries","JavaScript","Self-Hosted Registries"],"sub_categories":["Registry","Miscellaneous"],"readme":"= Citizen\n\nimage:https://github.com/outsideris/citizen/workflows/Unit%20tests/badge.svg[\"Unit Test Status\", link=\"https://github.com/outsideris/citizen/actions?query=workflow%3A%22Unit+tests%22+branch%3Amain\"]\nimage:https://github.com/outsideris/citizen/workflows/Integration%20Tests/badge.svg[\"Integration Test Status\", link=\"https://github.com/outsideris/citizen/actions?query=workflow%3A%22Integration+Tests%22+branch%3Amain\"]\nimage:https://app.fossa.io/api/projects/git%2Bgithub.com%2Foutsideris%2Fcitizen.svg?type=shield[\"FOSSA Status\", link=\"https://app.fossa.io/projects/git%2Bgithub.com%2Foutsideris%2Fcitizen?ref=badge_shield\"]\n\nA Private link:https://registry.terraform.io/[Terraform Module] and link:https://www.terraform.io/docs/internals/provider-registry-protocol.html[Terraform Provider] registry.\n\n== Requirements\n* HTTPS - Terraform module registry only support HTTPS.\n\n== Download\nlink:https://github.com/outsideris/citizen/releases/latest[Download the latest release!]\n\nAlso, you can use to launch the registry server.\nThe docker image is in link:https://github.com/users/outsideris/packages/container/package/citizen[GitHub Container Registry\n].\n\n[source, sh]\n....\n$ docker run -d -p \"3000:3000\" ghcr.io/outsideris/citizen:latest\n....\n\n== Server Usage\n\n=== `citizen server`\n\nTo launch the registry server\n[source, sh]\n....\n$ ./citizen server\n....\n\nIt will be launched at link:http://localhost:3000[http://localhost:3000]. You can check it at link:http://localhost:3000/health[http://localhost:3000/health].\n\nBecause link:https://www.terraform.io/[Terraform CLI] works with only HTTPS server, you should set up HTTPS in front of the registry server.\n\nIf you want to test it at local, you need a tool which provides HTTPS like link:https://ngrok.com/[ngrok].\n\nEnvironment variables:\n\n* `CITIZEN_DATABASE_TYPE`: Backend provider for registry metadata. Set to `mysql`, `mongodb` or `sqlite`.\n* `CITIZEN_DATABASE_URL`: The URL of the database. `protocol//username:password@hosts:port/database?options`\n* `CITIZEN_STORAGE`: Storage type to store module files. You can use `file`, `s3` or `gcs` type.\n** `s3` is for link:https://aws.amazon.com/ko/s3/[AWS S3].\n** `gcs` is for link:https://cloud.google.com/storage[Google Cloud Storage].\n* `CITIZEN_STORAGE_PATH`: A directory to save module files only if `CITIZEN_STORAGE` is `file` (absolute/relative path can be used).\n* `CITIZEN_STORAGE_BUCKET`: A S3 bucket to save module files only if `CITIZEN_STORAGE` is `s3` or `gcs`.(And AWS credentials required.)\n\nIf you want to use GCS as a storage, you need to link:https://cloud.google.com/docs/authentication/client-libraries[authenticate to Google Cloud services].\n\n=== Database migration\nTo migrate the database, you can use `citizen generate-migration` command.\nThe command will generate migration files which are `schema.prisma` and `migrations/` directory.\nBecause we use link:https://www.prisma.io/[prisma] to handle databases, you need to link:https://www.prisma.io/docs/concepts/components/prisma-cli/installation[install prisma CLI].\n\nThen, Set `CITIZEN_DATABASE_TYPE` and `CITIZEN_DATABASE_URL` envorinment variables\nand Run link:https://www.prisma.io/docs/reference/api-reference/command-reference#migrate-deploy[`prisma migrate deploy`] for Sqlite.\nFor MongoDB, migration is not required.\n\n== Client Usage\n\n=== `citizen module \u003cnamespace\u003e \u003cname\u003e \u003cprovider\u003e \u003cversion\u003e`\n\nSince link:https://registry.terraform.io/[official Terraform Module Registry] is integrated with GitHub, users can publish terraform modules if they just push it on GitHub.\n\nCitizen provides a special command to publish a module onto citizen registry server instead integrating GitHub.\n\nIn a module directory, you can publish your terraform module via a command below:\n[source, sh]\n....\n$ ./citizen module \u003cnamespace\u003e \u003cname\u003e \u003cprovider\u003e \u003cversion\u003e\n....\n\nYou should set `CITIZEN_ADDR` as citizen registry server address which you will publish your modules to. e.g. `https://registry.example.com`.\n\n=== Examples\nIf you have ALB module in `./alb` directory, and your registry server is launched at `https://registry.example.com`, you run below command in `./alb` directory to publish ALB module.\n[source, sh]\n....\n$ CITIZEN_ADDR=https://registry.example.com \\\n  citizen module dev-team alb aws 0.1.0\n....\n\nThen, you can define it in your terraform file like this:\n....\nmodule \"alb\" {\n  source = \"registry.example.com/dev-team/alb/aws\"\n  version = \"0.1.0\"\n}\n....\n\n=== `citizen provider \u003cnamespace\u003e \u003ctype\u003e \u003cversion\u003e [protocols]`\n\nCitizen provides a special command to publish providers onto citizen.\n\n- `-g, --gpg-key \u003cgpgkey\u003e`: GPG key to sign your SHA256SUMS.\n\n* You need to publish your provider with your GPG public key to terraform registry.\nOtherwise, terraform will refuse to install providers.\nTerraform official resistry manage partners' public keys,\nbut, each provider version has own public key and signature in citizen registry.\n\nYou must first link:https://www.terraform.io/docs/registry/providers/publishing.html[build and package], citizen\nexpects following files in the provider location:\n\n- `\u003cnamespace\u003e-\u003ctype\u003e_\u003cversion\u003e_\u003cos\u003e_\u003carch\u003e.zip` (one per os/arch combination)\n\nWhere `\u003cnamespace\u003e` and `\u003ctype\u003e` is a name of the provider and `\u003cversion\u003e` is a provider\nversion in the `MAJOR.MINOR.PATCH` version format.\n\nCitizen will generate a SHA256SUMS file and a GPG signature file automatically for you:\nFollowing files will be generated in your directory during publising provider.\nSo, You don't need prepare theses files.\n\n* `\u003cnamespace\u003e-\u003ctype\u003e_\u003cversion\u003e_SHA256SUMS`\n* `\u003cnamespace\u003e-\u003ctype\u003e_\u003cversion\u003e_SHA256SUMS.sig`\n\nTherefore, `shasum` and `gpg` commands should be available in your machine.\n\nIn a provider directory, you can publish your terraform provider via a command below:\n[source, sh]\n....\n$ ./citizen provider \u003cnamespace\u003e \u003ctype\u003e \u003cversion\u003e [protocols]\n....\n\n`[protocols]` is comma separated Terraform provider API versions, with `MAJOR.MINOR`.\n\nYou should set `CITIZEN_ADDR` as citizen registry server address which you will publish your modules to. e.g. `https://registry.example.com`.\n\n=== Examples\nIf you have ALB provider in `./utilities` directory, and your registry server is launched at `https://registry.example.com`,\nyou run below command in `./utilities` directory to publish utilities provider.\n[source, sh]\n....\n$ CITIZEN_ADDR=https://registry.example.com \\\n  citizen provider dev-team utilities 0.1.0 4.1,5.0\n....\n\nThen, you can define it in your terraform file like this:\n....\nprovider \"utilities\" {\n}\n\nterraform {\n  required_providers {\n    utilities = {\n      source = \"registry.example.com/dev-team/utilities\"\n      version = \"0.1.0\"\n    }\n  }\n}\n....\n\n== Development\nNode.js 16+ required\n\nSet environment variables, see above.\n\n[source, sh]\n....\n$ ./bin/citizen server\n$ ./bin/citizen module\n$ ./bin/citizen provider\n....\n\n=== Test\nSet at least a storage path and the s3 bucket name variables for the tests to succeed.\nYou need to be able to access the bucket, so you probably want to have an active aws or aws-vault profile.\n\nRun mongodb as replica set first like:\n[source, sh]\n....\n$ docker-compose -f test/docker-compose-mongodb-cluster.yaml up\n....\n\nRun MySQL with docker\n[source, sh]\n....\ndocker run --rm -p 3306:3306 --name mysql-citizen -e MYSQL_ROOT_PASSWORD=citizen -e MYSQL_DATABASE=citizen mysql\n....\n\nRun the tests:\n[source, sh]\n....\n$ npm test\n....\n\nRun the tests with the environment variables prefixed:\n[source, sh]\n....\n$ CITIZEN_STORAGE_PATH=storage CITIZEN_STORAGE_BUCKET=terraform-registry-modules npm test\n....\n\n=== Build distributions\n\n[source, sh]\n....\n$ npm run client\n$ npm run build\n....\n\nIt will generate prisma clients for databases.\n\nUnder ``dist/``,\ncitizen binaries for linux, darwin(amd64/arm64) and windows made.\n\n== License\nimage:https://app.fossa.io/api/projects/git%2Bgithub.com%2Foutsideris%2Fcitizen.svg?type=large[\"FOSSA Status\", link=\"https://app.fossa.io/projects/git%2Bgithub.com%2Foutsideris%2Fcitizen?ref=badge_large\"]\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foutsideris%2Fcitizen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foutsideris%2Fcitizen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foutsideris%2Fcitizen/lists"}