Merge pull request #23 from docker/contributions-and-readme

Setup readme and dev contributions

CONTRIBUTING.md

@@ -15,6 +15,58 @@ Thank you for considering contributing to the Docker Terraform Provider! We welc
 6. Make sure to test your changes
 7. When updating documentation, please see our guidance for documentation contributions (TODO)
 
+## Local Development Setup
+### Prerequisites:
+- `make`, `git`, `bash`
+- [Terraform](https://developer.hashicorp.com/terraform/downloads) >= 1.1
+- [Go](https://golang.org/doc/install) >= 1.21 
+  - Ensure your [GOPATH](http://golang.org/doc/code.html#GOPATH) is correctly setup, as well as adding `$GOPATH/bin` to your `$PATH`
+
+1. Clone `terraform-provider-docker`
+```
+git clone https://github.com/docker/terraform-provider-docker
+```
+2. Install provider & setup `~/.terrraformrc` making `registry.terraform.io/docker/docker` reference your local installation
+```
+make local-build
+```
+3. Setup your Docker Hub username & password
+```
+export DOCKER_USERNAME=$(yourusername)
+export DOCKER_PASSWORD=$(yourpassword)
+```
+4. Run an example build!
+```
+cd examples && terraform plan
+```
+Note, when you run the `terraform plan` you should see a warning, this ensures that you using the locally installed provider and not the publically available provider.
+
+> │ Warning: Provider development overrides are in effect
+
+Happy developing!
+
+## Testing
+
+Run full test suite:
+```
+make testacc
+```
+
+Run an individual test:
+```
+TF_ACC=1 go test ./internal/provider -v -timeout 120m -run TestFuncName
+```
+where `TestFuncName` is the testing function within the `_test.go` file.
+
+
+## Environment Variables
+```
+# enable debug logging
+export TF_LOG=DEBUG
+export TF_LOG_PATH="/PATH/TO/YOUR/LOG_FILE.log"
+...
+```
+
 ## Getting Help
 If you have any questions or need assistance, please reach out to us through in the DTP Slack Channel (TODO)
 

Makefile

@@ -1,15 +1,48 @@
+# Default target
 default: testacc
 
 # Run acceptance tests
 .PHONY: testacc
 testacc:
 	TF_ACC=1 go test ./... -v $(TESTARGS) -timeout 120m
 
+# Install the provider binary to GOBIN
 .PHONY: install
 install:
 	go install .
 
+# Generate documentation
 .PHONY: docs
 docs:
 	go generate ./...
 
+# Setup local development environment
+.PHONY: local-build
+local-build: install setup-terraformrc
+
+# Setup or update ~/.terraformrc with GOBIN path for docker/docker provider
+.PHONY: setup-terraformrc
+setup-terraformrc:
+	@echo "Setting up ~/.terraformrc for local development..."
+	@GOBIN_PATH=$$(go env GOBIN); \
+	if [ -z "$$GOBIN_PATH" ]; then \
+		echo "GOBIN is not set. Defaulting to GOPATH/bin"; \
+		GOBIN_PATH=$$(go env GOPATH)/bin; \
+	fi; \
+	echo "Using GOBIN_PATH=$$GOBIN_PATH"; \
+	if [ ! -f ~/.terraformrc ]; then \
+		echo 'provider_installation {' > ~/.terraformrc; \
+		echo '  dev_overrides {' >> ~/.terraformrc; \
+		echo "    \"registry.terraform.io/docker/docker\" = \"$$GOBIN_PATH\"" >> ~/.terraformrc; \
+		echo '  }' >> ~/.terraformrc; \
+		echo '  direct {}' >> ~/.terraformrc; \
+		echo '}' >> ~/.terraformrc; \
+		echo "~/.terraformrc has been created and set up for local development."; \
+	else \
+		if grep -q 'registry.terraform.io/docker/docker' ~/.terraformrc; then \
+			echo "The override for registry.terraform.io/docker/docker already exists in ~/.terraformrc."; \
+		else \
+			awk '/dev_overrides/ {print; print "    \"registry.terraform.io/docker/docker\" = \"'"$$GOBIN_PATH"'\""; next}1' ~/.terraformrc > ~/.terraformrc.tmp && mv ~/.terraformrc.tmp ~/.terraformrc; \
+			echo "Added the override for registry.terraform.io/docker/docker to ~/.terraformrc."; \
+		fi; \
+	fi

README.md

@@ -1,77 +1,47 @@
 # Docker Hub Terraform Provider
+This project is used to manage Docker resources (such as repositories, teams, organization settings, and more) using Terraform. It allows users to define Docker infrastructure as code, integrating Docker services into their Terraform workflows. The Terraform Registry page for this provider can be found [here](https://registry.terraform.io/providers/docker/docker/).
 
-_This template repository is built on the [Terraform Plugin Framework](https://github.com/hashicorp/terraform-plugin-framework). The template repository built on the [Terraform Plugin SDK](https://github.com/hashicorp/terraform-plugin-sdk) can be found at [terraform-provider-scaffolding](https://github.com/hashicorp/terraform-provider-scaffolding). See [Which SDK Should I Use?](https://developer.hashicorp.com/terraform/plugin/framework-benefits) in the Terraform documentation for additional information._
-
-This repository is a _template_ for a [Terraform](https://www.terraform.io) provider. It is intended as a starting point for creating Terraform providers, containing:
-
-- A resource and a data source (`internal/provider/`),
-- Examples (`examples/`) and generated documentation (`docs/`),
-- Miscellaneous meta files.
-
-These files contain boilerplate code that you will need to edit to create your own Terraform provider. Tutorials for creating Terraform providers can be found on the [HashiCorp Developer](https://developer.hashicorp.com/terraform/tutorials/providers-plugin-framework) platform. _Terraform Plugin Framework specific guides are titled accordingly._
-
-Please see the [GitHub template repository documentation](https://help.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-repository-from-a-template) for how to create a new repository from this template on GitHub.
-
-Once you've written your provider, you'll want to [publish it on the Terraform Registry](https://developer.hashicorp.com/terraform/registry/providers/publishing) so that others can use it.
+> [!WARNING]
+> This project is **not** for managing objects in a local docker engine. If you would like to use Terraform to interact with a docker engine, [kreuzwerker/docker](https://registry.terraform.io/providers/kreuzwerker/docker/latest) is a fine provider.
 
 ## Requirements
 
-- [Terraform](https://developer.hashicorp.com/terraform/downloads) >= 1.9
-- [Go](https://golang.org/doc/install) >= 1.21
-
-## Building The Provider
+- [Terraform](https://developer.hashicorp.com/terraform/downloads) >= 1.1
+- [Go](https://golang.org/doc/install) >= 1.21 (to build the provider plugin)
 
-1. Clone the repository
-1. Enter the repository directory
-1. Build the provider using the Go `install` command:
+## Usage 
+Below is a basic example of how to use the Docker services Terraform provider to create a Docker repository. Using `DOCKER_USERNAME` and `DOCKER_PASSWORD` as an environment variable, you can use the following code:
 
-```shell
-go install
 ```
+terraform {
+  required_providers {
+    docker = {
+      source  = "docker/docker"
+      version = "~> 1.0"
+    }
+  }
+}
 
-## Adding Dependencies
-
-This provider uses [Go modules](https://github.com/golang/go/wiki/Modules).
-Please see the Go documentation for the most up to date information about using Go modules.
-
-To add a new dependency `github.com/author/dependency` to your Terraform provider:
+provider "docker" { }
 
-```shell
-go get github.com/author/dependency
-go mod tidy
+resource "docker_repository" "example" {
+  name        = "example-repo"
+  description = "This is an example Docker repository"
+  private     = true
+}
 ```
 
-Then commit the changes to `go.mod` and `go.sum`.
 
-## Using the provider
 
-Fill this in for each provider
+## Contributing 
+We welcome contributions to the Docker services Terraform provider, detailed documentation for contributing & building the provider can be found [here](https://github.com/docker/terraform-provider-docker/blob/main/CONTRIBUTING.md)
 
-## Developing the Provider
+## Roadmap
+Our roadmap is managed through GitHub issues. You can view upcoming features and enhancements, as well as report bugs or request new features, by visiting our [issues page](https://github.com/docker/terraform-provider-docker/issues?q=sort%3Aupdated-desc+is%3Aissue+is%3Aopen).
 
-If you wish to work on the provider, you'll first need [Go](http://www.golang.org) installed on your machine (see [Requirements](#requirements) above).
+## Support
 
-To compile the provider, run `go install`. This will build the provider and put the provider binary in the `$GOPATH/bin` directory.
+TODO: how much will we be supporting this & at what cadence?
 
-You will need to create a `.terraformrc` in your `$HOME` directory
-
-```
-provider_installation {
-  dev_overrides {
-    # replace this path with your $(go env GOBIN) path
-    "registry.terraform.io/docker/docker" = "<enter your $(go env GOBIN) path here>"
-  }
-
-  direct {}
-}
-```
-
-To generate or update documentation, run `go generate`.
-
-In order to run the full suite of Acceptance tests, run `make testacc`.
-
-_Note:_ Acceptance tests create real resources, and often cost money to run.
-
-```shell
-make testacc
-```
+## License
+This project is licensed under the Apache 2.0 License. See the [LICENSE](https://github.com/docker/terraform-provider-docker/blob/main/LICENSE) file for more information.