From 63563e57dbb50c5ccf2ff01d225038ba7a5cb7f2 Mon Sep 17 00:00:00 2001 From: Atif Ali Date: Mon, 16 Feb 2026 22:29:48 +0500 Subject: [PATCH] docs: add registry mirroring guide for Artifactory (#22025) Verified to be working locally. --------- Co-authored-by: Phorcys <57866459+phorcys420@users.noreply.github.com> --- .../templates/extending-templates/modules.md | 30 ++- docs/install/airgap.md | 6 +- docs/install/registry-mirror-artifactory.md | 198 ++++++++++++++++++ docs/manifest.json | 5 + 4 files changed, 227 insertions(+), 12 deletions(-) create mode 100644 docs/install/registry-mirror-artifactory.md diff --git a/docs/admin/templates/extending-templates/modules.md b/docs/admin/templates/extending-templates/modules.md index 39aba3f2d3..ebd249f89b 100644 --- a/docs/admin/templates/extending-templates/modules.md +++ b/docs/admin/templates/extending-templates/modules.md @@ -54,21 +54,31 @@ For a full list of available modules please check ## Offline installations -In offline and restricted deployments, there are two ways to fetch modules. +In offline and restricted deployments, there are three ways to fetch modules. -1. Artifactory -2. Private git repository +1. Artifactory Remote Terraform Repository (Recommended) +2. Artifactory Local Repository (manual publishing) +3. Private git repository -### Artifactory +### Artifactory Remote Terraform Repository (Recommended) -Air gapped users can clone the [coder/registry](https://github.com/coder/registry/) +Configure Artifactory as a **Remote Terraform Repository** that proxies and +caches the Coder registry. This approach provides automatic updates and +requires no manual synchronization. + +See [Mirror the Coder Registry with JFrog Artifactory](../../../install/registry-mirror-artifactory.md) +for complete setup instructions. + +### Artifactory Local Repository + +Air-gapped users can clone the [coder/registry](https://github.com/coder/registry/) repo and publish a [local terraform module repository](https://jfrog.com/help/r/jfrog-artifactory-documentation/set-up-a-terraform-module/provider-registry) to resolve modules via [Artifactory](https://jfrog.com/artifactory/). 1. Create a local-terraform-repository with name `coder-modules-local` -2. Create a virtual repository with name `tf` -3. Follow the below instructions to publish coder modules to Artifactory +1. Create a virtual repository with name `tf` +1. Follow the below instructions to publish coder modules to Artifactory ```shell git clone https://github.com/coder/registry @@ -77,9 +87,9 @@ to resolve modules via [Artifactory](https://jfrog.com/artifactory/). jf tf p --namespace="coder" --provider="coder" --tag="1.0.0" ``` -4. Generate a token with access to the `tf` repo and set an `ENV` variable +1. Generate a token with access to the `tf` repo and set an `ENV` variable `TF_TOKEN_example.jfrog.io="XXXXXXXXXXXXXXX"` on the Coder provisioner. -5. Create a file `.terraformrc` with following content and mount at +1. Create a file `.terraformrc` with following content and mount at `/home/coder/.terraformrc` within the Coder provisioner. ```tf @@ -93,7 +103,7 @@ to resolve modules via [Artifactory](https://jfrog.com/artifactory/). } ``` -6. Update module source as: +1. Update module source as: ```tf module "module-name" { diff --git a/docs/install/airgap.md b/docs/install/airgap.md index 30a4237e16..2a701e0349 100644 --- a/docs/install/airgap.md +++ b/docs/install/airgap.md @@ -235,8 +235,10 @@ accessible for your team to use. ## Coder Modules -To use Coder modules in offline installations please follow the instructions -[here](../admin/templates/extending-templates/modules.md#offline-installations). +To use Coder modules in offline installations, you can either: + +- [Mirror the Coder Registry with JFrog Artifactory](./registry-mirror-artifactory.md) (recommended) +- [Manually publish modules to Artifactory or use a private git repository](../admin/templates/extending-templates/modules.md#offline-installations) ## Firewall exceptions diff --git a/docs/install/registry-mirror-artifactory.md b/docs/install/registry-mirror-artifactory.md new file mode 100644 index 0000000000..f0c4b492c8 --- /dev/null +++ b/docs/install/registry-mirror-artifactory.md @@ -0,0 +1,198 @@ +# Mirror the Coder Registry with JFrog Artifactory + +This guide shows you how to use JFrog Artifactory to mirror the +[Coder Registry](https://registry.coder.com) for air-gapped or restricted +network deployments. + +By configuring Artifactory as a Remote Terraform Repository, you can: + +- **Proxy and cache** all Coder modules automatically +- **Keep modules updated** without manual synchronization +- **Support offline access** once modules are cached + +## Prerequisites + +- JFrog Artifactory instance (Cloud or self-hosted) +- Admin access to create repositories +- Artifactory user token for Terraform authentication + +## Step 1: Create the Remote Terraform Repository + +1. In Artifactory, go to **Administration > Repositories > Remote** + +1. Click **New Remote Repository** and select **Terraform** as the package type + +1. Configure the repository with these settings: + + | Setting | Value | + |------------------------|------------------------------| + | Repository Key | `coder-registry` | + | URL | `https://registry.coder.com` | + | Terraform Registry URL | `https://registry.coder.com` | + +1. Click **Create Remote Repository** + +## Step 2: Verify the Repository Configuration + +Test that Artifactory can proxy the Coder registry by querying the module +versions API: + +```sh +curl -u ':' \ + 'https:///artifactory/api/terraform/coder-registry/v1/modules/coder/code-server/coder/versions' +``` + +You should see a JSON response listing all available versions of the +`code-server` module. + +## Step 3: Configure Terraform CLI + +Create or update your Terraform CLI configuration file to use Artifactory. + +On Linux/macOS, create `~/.terraformrc`. On Windows, create `%APPDATA%\terraform.rc`. + +```hcl +host "" { + services = { + "modules.v1" = "https:///artifactory/api/terraform/coder-registry/v1/modules/" + } +} + +credentials "" { + token = "" +} +``` + +Replace: + +- `` with your Artifactory hostname (e.g., + `artifactory.example.com` or `mycompany.jfrog.io`) +- `` with your Artifactory access token with read permissions to the `coder-registry` repository + +> [!NOTE] +> The `host` block with `services` is required because Artifactory's global +> service discovery endpoint doesn't include the repository name in the modules +> path. This explicitly tells Terraform where to find modules in your specific +> repository. + +## Step 4: Update Template Module Sources + +Update your Coder templates to use Artifactory instead of the public registry: + +```tf +# Before: Direct from Coder registry +module "code-server" { + source = "registry.coder.com/coder/code-server/coder" + version = "1.4.2" + agent_id = coder_agent.main.id +} + +# After: Through Artifactory mirror +module "code-server" { + source = "https:///coder/code-server/coder" + version = "1.4.2" + agent_id = coder_agent.main.id +} +``` + +## Step 5: Configure Coder Server or Provisioners + +For Coder to use the Artifactory mirror, configure the Terraform CLI on your +Coder server or external provisioners. + +
+ +### Kubernetes Deployment + +Create a secret with the Terraform configuration: + +```sh +kubectl create secret generic terraform-config \ + --from-file=.terraformrc=./terraformrc \ + -n coder +``` + +Update your Helm values: + +```yaml +coder: + volumes: + - name: terraform-config + secret: + secretName: terraform-config + volumeMounts: + - name: terraform-config + mountPath: /home/coder/.terraformrc + subPath: .terraformrc + readOnly: true + env: + - name: TF_CLI_CONFIG_FILE + value: /home/coder/.terraformrc +``` + +### Docker Deployment + +Mount the `.terraformrc` file into the Coder container: + +```yaml +# docker-compose.yaml +services: + coder: + volumes: + - ./terraformrc:/home/coder/.terraformrc:ro + environment: + TF_CLI_CONFIG_FILE: /home/coder/.terraformrc +``` + +
+ +## Caching Behavior + +Artifactory uses **lazy caching**, meaning modules are cached on first request. +For fully air-gapped deployments, pre-warm the cache while connected to the +internet: + +1. Create a test template that references all modules you need +1. Run `terraform init` to trigger downloads +1. Verify modules appear in Artifactory under `coder-registry-cache` + +Once cached, modules remain available even without internet connectivity. + +## Supported Namespaces + +The Artifactory mirror supports all namespaces from the Coder registry: + +| Namespace | Description | Example Module | +|--------------|---------------------------|------------------------------------| +| `coder` | Official Coder modules | `code-server`, `jetbrains-gateway` | +| `coder-labs` | Experimental modules | `cursor-cli`, `copilot` | +| Community | Third-party contributions | Various | + +All modules use the same source format: + +```tf +source = "///coder" +``` + +## Troubleshooting + +### Module not found errors + +Verify your `.terraformrc` includes both the `host` block with `services` and +the `credentials` block. The `host.services` configuration is required for +Artifactory. + +### 401 Unauthorized errors + +Check that your Artifactory token is valid and has read access to the +`coder-registry` repository. + +### Modules not caching + +Ensure the remote repository URL is set to `https://registry.coder.com` and not other paths. + +## Next Steps + +- [Coder Module Registry](https://registry.coder.com/modules) +- [JFrog Terraform Registry Documentation](https://jfrog.com/help/r/jfrog-artifactory-documentation/terraform-registry) +- [Air-gapped Deployments](./airgap.md) diff --git a/docs/manifest.json b/docs/manifest.json index a1faf1a4b7..7805e79b5b 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -1193,6 +1193,11 @@ "description": "Integrate Coder with JFrog Artifactory", "path": "./admin/integrations/jfrog-artifactory.md" }, + { + "title": "Mirror Coder Registry with Artifactory", + "description": "Use JFrog Artifactory to mirror the Coder Registry for air-gapped deployments", + "path": "./install/registry-mirror-artifactory.md" + }, { "title": "Istio Integration", "description": "Integrate Coder with Istio",