Registry docs

frontend/docs/index.md

@@ -0,0 +1,30 @@
+# The OpenTofu Registry
+
+The OpenTofu Registry provides an API for OpenTofu to locate providers and modules. This documentation will guide you through the most important steps in using the registry or publishing your modules and providers. 
+
+## For users
+
+This section contains the documentation for OpenTofu users.
+
+- [Overview](/docs/users)
+- [Using a provider](/docs/users/providers)
+- [Using a module](/docs/users/modules)
+
+## For provider authors
+
+This section guides you through the steps of creating and publishing an OpenTofu provider.
+
+- [Overview](/docs/providers)
+- [Creating a provider](/docs/providers/creating)
+- [Writing docs for your provider](/docs/providers/docs)
+- [Publishing your provider](/docs/providers/publishing)
+- [Adding a provider to the registry](/docs/providers/adding)
+
+## For module authors
+
+This section shows you how to create and publish a module.
+
+- [Overview](/docs/modules)
+- [Creating a module](/docs/modules/creating)
+- [Publishing a module](/docs/modules/publishing)
+- [Adding a module to the OpenTofu Registry](/docs/modules/adding)

frontend/docs/modules/adding.md

@@ -0,0 +1,11 @@
+# Adding your module to the OpenTofu registry
+
+Once you have [published your module](/docs/modules/publishing), you can add your module to the OpenTofu Registry. You can do this by [creating an issue](https://github.com/opentofu/registry/issues/new/choose) on the OpenTofu Registry GitHub repository.
+
+Here you will have to provide your username/organization name and repository name, which will translate to a module name. For example, consider the following repository:
+
+```
+YOURNAME/terraform-NAME-TARGETSYSTEM
+```
+
+This will translate to a module address your users can reference as `YOURNAME/NAME/TARGETSYSTEM`.

frontend/docs/modules/creating.md

@@ -0,0 +1,35 @@
+# Creating an OpenTofu module
+
+Any OpenTofu project can be a reusable module others can use. By pushing it to GitHub and then publishing the link to your module in the OpenTofu Registry, anyone can easily find and use it.
+
+In order to create a module for reuse, simply write your OpenTofu code the way you normally would and create [variables](https://opentofu.org/docs/language/values/variables/) for configuration.
+
+Your module may also create resources that a user may want to use further. For example, you may create a virtual machine and want to supply your user with the ID of that virtual machine. To return values from your module, you can use [output](https://opentofu.org/docs/language/values/outputs/) blocks.
+
+You can read more about how modules work [in the OpenTofu documentation](https://opentofu.org/docs/language/modules/).
+
+## Readme
+
+Once the code is done, make sure that you add a `README.md` file and explain to your users how to use your module. This file will show up in the Registry Search if the license allows for it.
+
+## License
+
+In order for your module to show up in the OpenTofu Registry Search, your module should be licensed under one of the [supported licenses](https://github.com/opentofu/registry-ui/blob/main/licenses.json). If your module is not under one of these licenses, your module will be findable in the Registry Search, but no other data will be displayed.
+
+## Submodules
+
+If you want to structure your modules further, you can use submodules you can place in subdirectories. To make the submodules show up in the Registry Search, place your submodules in the `modules/MODULENAME` directory in your module.
+
+You can add a `README.md` file to your submodule to provide more information about your submodule.
+
+## Examples
+
+Similar in structure to submodules, examples provide your users with an easy way to get into using your module. To make your example show up in the OpenTofu Registry Search, place the example project into the `examples/EXAMPLENAME` folder and add a `README.md` file.
+
+## Testing your module
+
+Tests are a great way to ensure that your module stays working when community pull requests come in. The [`tofu test` command](https://opentofu.org/docs/cli/commands/test/) has a host of tools to let you write automated tests for your module so you can merge pull requests safely.
+
+## Publishing your module
+
+Once you are happy with your module, [proceed to publishing it](/docs/modules/publishing).

frontend/docs/modules/index.md

@@ -0,0 +1,7 @@
+# The OpenTofu Registry for Module Authors
+
+This section shows you how to create and publish a module.
+
+- [Creating a module](/docs/modules/creating)
+- [Publishing a module](/docs/modules/publishing)
+- [Adding a module to the OpenTofu Registry](/docs/modules/adding)

frontend/docs/modules/publishing.md

@@ -0,0 +1,7 @@
+# Publishing an OpenTofu module
+
+You can host OpenTofu modules in any git repository. However, if you would like to publish the module in the OpenTofu Registry, you will need to host it on [GitHub](https://docs.github.com/en/get-started/start-your-journey).
+
+Once you pushed your code, make sure to [create a tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) following [semantic versioning](https://semver.org/). This tag will translate to a version in the OpenTofu registry.
+
+Once you have pushed your tag, you can now [add the module to the Registry](/docs/modules/adding).

frontend/docs/providers/adding.md

@@ -0,0 +1,19 @@
+# Adding your provider to the OpenTofu Registry
+
+Once you have [published your provider](/docs/providers/publishing), you are ready to add your provider to the OpenTofu Registry. You only need to perform these steps once, the OpenTofu Registry will automatically discover new versions you publish.
+
+## Adding the provider
+
+To add your provider, please go to the [OpenTofu Registry repository](https://github.com/opentofu/registry/issues/new/choose) and select `Submit new Provider`. In the `Provider Repository` field please enter `YOURNAME/terraform-provider-YOURPROVIDER` and submit the issue. An OpenTofu team member will review your submission and merge it into the Registry. Your provider should be live within an hour after merging. 
+
+## Adding the GPG key
+
+After your provider is merged, you can proceed to add your GPG key. You will need to perform the following steps:
+
+1. Export your *public* GPG key into a text file with ASCII-armor.
+2. If your provider is located in an organization, make sure you make [your membership in the organization public](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/publicizing-or-hiding-organization-membership). This is required to validate you have the rights to publish a GPG key.
+3. Go to the [OpenTofu Registry repository](https://github.com/opentofu/registry/issues/new/choose) and select `Submit new Provider Signing Key`.
+4. In the `Provider Namespace` field enter your username or organization name.
+5. In the `Provider GPG Key` field paste your GPG key.
+
+~> The GPG key applies to all providers under your username or organization. Don't submit a GPG key if you have providers that are not signed or are signed with a key you don't have.

frontend/docs/providers/creating.md

@@ -0,0 +1,39 @@
+# Creating an OpenTofu provider
+
+OpenTofu, itself a fork of Terraform, uses the [Terraform plugin protocol](https://developer.hashicorp.com/terraform/plugin/terraform-plugin-protocol) in order to communicate with providers. Any provider implementing this protocol will also work with OpenTofu.
+
+## Using the Terraform Plugin Framework (recommended)
+
+As per the recommendation from HashiCorp for Terraform, the easiest option to write a provider is using the Terraform Plugin Framework. You can find detailed guides for this in the [Terraform documentation](https://developer.hashicorp.com/terraform/plugin/framework).
+
+## Manually (only for the adventurous)
+
+~> Support for programming languages other than Go and bypassing the official SDK/framework is very limited. For production use we recommend using Go and the [Terraform Plugin Framework](https://developer.hashicorp.com/terraform/plugin/framework).
+
+OpenTofu supports providers written in any language as long as they can be compiled to a static binary. Providers written in languages that don't compile to a static binary may or may not work, depending on the host operating system.
+
+In order to start the provider OpenTofu uses [go-plugin](https://github.com/hashicorp/go-plugin). This process is as follows:
+
+1. OpenTofu starts the plugin with the `PLUGIN_MIN_PORT`, `PLUGIN_MAX_PORT`, `PLUGIN_PROTOCOL_VERSIONS` and the `PLUGIN_CLIENT_CERT` environment variables set. While OpenTofu currently doesn't use them, your implementation should also implement handling the `PLUGIN_UNIX_SOCKET_DIR`, `PLUGIN_UNIX_SOCKET_GROUP`, and `PLUGIN_MULTIPLEX_GRPC` environment variables.
+2. On Windows, the plugin will scan from `PLUGIN_MIN_PORT` and `PLUGIN_MAX_PORT` to find an open port and open a TCP listen socket on that port, binding to `127.0.0.1`.
+3. On all other systems, the plugin will create a Unix socket in a directory of its choosing. (See the note about the additional environment variables here.)
+4. The plugin chooses one of the `PLUGIN_PROTOCOL_VERSIONS` to support. This can be currently version `5` or `6`.
+5. The plugin writes the following line to the stdout, terminated by a newline: `<CoreProtocolVersion>|<ProtocolVersion>|<SocketType>|<SocketAddr>|<Protocol>|<ServerCert>\n`. The `<CoreProtocolVersion>` is always `1` and references the go-plugin protocol version. The `<ProtocolVersion>` references the plugin protocol version must be `5` or `6` for OpenTofu. The `<SocketType>` can only be `unix` or `tcp`, with the corresponding `<SocketAddr>` set. The `<Protocol>` must always be `grpc` for OpenTofu. Finally, the `<ServerCert>` may contain a raw (not PEM-encoded) certificate with base64 encoding to secure the connection between the plugin and OpenTofu in conjunction with `PLUGIN_CLIENT_CERT`.
+6. OpenTofu now sends GRPC requests to the plugin. You can find the protocol definitions for these requests [in the OpenTofu repository](https://github.com/opentofu/opentofu/tree/main/docs/plugin-protocol/). We also recommend reading the [Terraform Plugin Protocol documentation](https://developer.hashicorp.com/terraform/plugin/terraform-plugin-protocol).
+7. The plugin may write logs to stderr, which OpenTofu records as plugin logs.
+
+## OpenTofu-specific enhancements
+
+### Configured functions
+
+When calling provider-defined functions (introduced in OpenTofu 1.7 and Terraform 1.8), Terraform does not pass any configuration to the provider. This means, your functions cannot make use of provider configuration if you want to support Terraform. OpenTofu configures the provider, so your functions may make use of this configuration.
+
+## Things that don't work in OpenTofu (yet)
+
+### Moving resources between different types ([#1369](https://github.com/opentofu/opentofu/issues/1369))
+
+As of OpenTofu 1.8, OpenTofu does not yet implement using the `moved` block between resources of different types. See issue [#1369](https://github.com/opentofu/opentofu/issues/1369) for details.
+
+## Next steps
+
+Once you have written your provider code, you can proceed to [write your documentation](/docs/providers/docs).

frontend/docs/providers/docs.md

@@ -0,0 +1,30 @@
+# Writing documentation for your provider
+
+In order for your provider to show up in the OpenTofu Registry Search properly, you will need to write some documentation. Tools like [terraform-plugin-docs](https://github.com/hashicorp/terraform-plugin-docs) can help you by auto-generating much of the documentation based on your provider schema.
+
+## Documentation structure
+
+You can place your documentation in the `docs` folder in your repository. Please create the files using the following naming convention:
+
+- `/docs/guides/<guide>.md` for guides.
+- `/docs/resources/<resource>.md` for resources. (Note: if your resource is called `yourprovider_yourresource`, you should only include `yourresource` here.)
+- `/docs/data-sources/<data-source>.md` for resources. (Note: same as for resources)
+- `/docs/functions/<function>.md` for functions.
+
+Additionally, if you would like to support CDKTF, you can create the following documents:
+
+- `/docs/cdktf/[python|typescript|csharp|java|go]/resources/<resource>.md`
+- `/docs/cdktf/[python|typescript|csharp|java|go]/data-sources/<data-source>.md`
+- `/docs/cdktf/[python|typescript|csharp|java|go]/functions/<function>.md`
+
+You can include the following header (front matter) in your markdown files:
+
+```yaml
+---
+page_title: Title of the page
+subcategory: Subcategory to place the page in on the sidebar (optional)
+description: Description of the page
+---
+```
+
+Once you have written your documentation, you can [proceed to publish your provider](/docs/providers/publishing).

frontend/docs/providers/index.md

@@ -0,0 +1,10 @@
+# The OpenTofu Registry for Provider Authors
+
+This section of the documentation guides you through the basic steps of creating and publishing a provider in the OpenTofu Registry. The documentation assumes you are familiar with the Go programming language.
+
+## In this section
+
+- [Creating a provider](/docs/providers/creating)
+- [Writing docs for your provider](/docs/providers/docs)
+- [Publishing your provider](/docs/providers/publishing)
+- [Adding a provider to the registry](/docs/providers/adding)

frontend/docs/providers/publishing.md

@@ -0,0 +1,45 @@
+# Publishing a provider version
+
+Once you have finished [creating your provider](/docs/providers/creating) and [wrote your documentation](/docs/providers/docs), you can proceed to publish your provider. First, create a GitHub repository named `terraform-provider-YOURNAME` and publish your source code in this repository. You can then proceed to [create a GitHub release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository). 
+
+~> Note, that your release name **must** start with a `v` and must follow [semantic versioning](https://semver.org/).
+
+## Using the scaffolding (recommended)
+
+If you used the [terraform-provider-scaffolding-framework](https://github.com/hashicorp/terraform-provider-scaffolding-framework) as your starting point, it also includes the necessary GitHub Actions and [goreleaser file](https://github.com/hashicorp/terraform-provider-scaffolding-framework/blob/main/.goreleaser.yml) needed to create a release.
+
+You will need to create the secrets called `GPG_PRIVATE_KEY` and `PASSPHRASE` in order to sign your release. GPG keys ensure the integrity of your provider binaries. While OpenTofu allows you to submit a provider without a GPG key for compatibility reasons, adding a GPG key helps keep your users safe and is also required if you intend to submit your provider to the Terraform Registry. The workflow in the terraform-provider-scaffolding-framework repository assumes you will use a GPG key.
+
+Please follow the [GitHub documentation on generating a GPG key](https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key). You do not need to add the public key to your GitHub account, but instead you can [submit it to the OpenTofu Registry](/docs/providers/adding) in the next step.
+
+~> Keep your private key safe! If your private key becomes public, others will be able to produce correctly signed binaries for your provider! The private key should only be in your GitHub secrets and backed up on your own computer. You should never need to submit the private key anywhere.
+
+Once this is set up, proceed to create a release named `vYOURVERSION` on GitHub and wait for the GitHub Actions job to complete.
+
+## Manually (for the adventurous)
+
+If you are feeling adventurous, you can also create your release artifacts manually. You will need to produce the following artifacts:
+
+- `terraform-provider-YOURNAME_VERSION_PLATFORM_ARCH.zip` containing your provider binary named `terraform-provider-YOURNAME` or `terraform-provider-YOURNAME.exe` and any supplemental files. (e.g. `terraform-provider-aws_5.68.0_darwin_amd64.zip`)
+- `terraform-provider-YOURNAME_SHA256SUMS` containing the SHA256 checksums and filenames for all files in your release, one in each line in the format of `<checksum>  <filename>\n` (e.g. `0501ccb379b74832366860699ca6d5993b164ec44314a054453877d39c384869  terraform-provider-aws_5.68.0_darwin_amd64.zip`)
+- `terraform-provider-YOURNAME_SHA256SUMS.sig` containing a detached GPG signature for the SHA256SUMS file (without ASCII-armor). This file is optional for OpenTofu.
+
+~> The versions in the filenames **must not** contain the `v` prefix.
+
+OpenTofu supports the following platform names:
+
+- `darwin` (MacOS)
+- `linux`
+- `windows`
+- `freebsd`
+- `openbsd`
+- `solaris`
+
+You can use these in conjunction with the following architecture names:
+
+- `amd64`
+- `arm64`
+- `386`
+- `arm`
+
+Once you are done, you can upload your release to GitHub and [submit your provider to the OpenTofu Registry](/docs/providers/adding) and the [Terrafom Registry](https://developer.hashicorp.com/terraform/registry/providers/publishing).

frontend/docs/sidebar.json

@@ -0,0 +1,82 @@
+[
+  {
+    "title": "Overview",
+    "path": "index.md",
+    "slug": ""
+  },
+  {
+    "title": "For users",
+    "items": [
+      {
+        "title": "Overview",
+        "path": "users/index.md",
+        "slug": "users"
+      },
+      {
+        "title": "Using a provider",
+        "path": "users/providers.md",
+        "slug": "users/providers"
+      },
+      {
+        "title": "Using a module",
+        "path": "users/modules.md",
+        "slug": "users/modules"
+      }
+    ]
+  },
+  {
+    "title": "For provider authors",
+    "items": [
+      {
+        "title": "Overview",
+        "path": "providers/index.md",
+        "slug": "providers"
+      },
+      {
+        "title": "Creating a provider",
+        "path": "providers/creating.md",
+        "slug": "providers/creating"
+      },
+      {
+        "title": "Writing docs for your provider",
+        "path": "providers/docs.md",
+        "slug": "providers/docs"
+      },
+      {
+        "title": "Publishing your provider",
+        "path": "providers/publishing.md",
+        "slug": "providers/publishing"
+      },
+      {
+        "title": "Adding a provider to the registry",
+        "path": "providers/adding.md",
+        "slug": "providers/adding"
+      }
+    ]
+  },
+  {
+    "title": "For module authors",
+    "items": [
+      {
+        "title": "Overview",
+        "path": "modules/index.md",
+        "slug": "modules"
+      },
+      {
+        "title": "Creating a module",
+        "path": "modules/creating.md",
+        "slug": "modules/creating"
+      },
+      {
+        "title": "Publishing a module",
+        "path": "modules/publishing.md",
+        "slug": "modules/publishing"
+      },
+      {
+        "title": "Adding a module to the Registry",
+        "path": "modules/adding.md",
+        "slug": "modules/adding"
+      }
+    ]
+  }
+]

frontend/docs/users/index.md

@@ -0,0 +1,8 @@
+# The OpenTofu Registry for Users
+
+OpenTofu is a tool that works with integrations made by the community called *providers*. In addition to that, community-made modules simplify many common tasks. The OpenTofu Registry contains an index pointing to thousands of providers and thousands of modules on GitHub you can use. You can install them automatically by adding a code snippet to your project and running `tofu init`.
+
+## In this chapter
+
+- [Using a provider](/docs/users/providers)
+- [Using a module](/docs/users/modules)