docs: add put customization document

www/content/put.md

@@ -0,0 +1,92 @@
+---
+title: Put
+series: customization
+hideFromIndex: true
+weight: 120
+---
+
+Since [vX.Y.Z](https://github.com/goreleaser/goreleaser/releases/tag/vX.Y.Z),
+GoReleaser supports building and pushing artifacts to HTTP servers using simple HTTP PUT requests.
+
+## How it works
+
+You can declare multiple Put instances.
+All binaries generated by your `builds` section will be pushed to each configured Put.
+
+If you have only one Put instance, the configuration is as easy as adding the
+upload target and a username to your `.goreleaser.yml` file:
+
+```yaml
+puts:
+  - name: production
+    target: http://some.server/some/path/example-repo-local/{{ .ProjectName }}/{{ .Version }}/
+    username: goreleaser
+```
+
+Prerequisites:
+
+- An HTTP server accepting PUT requests
+- A user + password with grants to upload an artifact using PUT requests (if the server requires it)
+
+### Target
+
+The `target` is the URL to upload the artifacts to (_without_ the name of the artifact).
+
+An example configuration for `goreleaser` in upload mode `binary` with the target can look like
+
+```yaml
+- mode: binary
+  target: 'http://some.server/some/path/example-repo-local/{{ .ProjectName }}/{{ .Version }}/{{ .Os }}/{{ .Arch }}{{ if .Arm }}{{ .Arm }}{{ end }}'
+```
+
+and will result in an HTTP PUT request sent to `http://some.server/some/path/example-repo-local/goreleaser/1.0.0/Darwin/x86_64/goreleaser`.
+
+Supported variables:
+
+- Version
+- Tag
+- ProjectName
+- Os
+- Arch
+- Arm
+
+_Attention_: Variables _Os_, _Arch_ and _Arm_ are only supported in upload mode `binary`.
+
+### Password
+
+Your configured username needs to be valid against your HTTP server.
+
+The password will be stored in a environment variable.
+The configured name of your HTTP server will be used.
+This way we support auth for multiple instances.
+This also means that the `name` per configured instance needs to be unique
+per goreleaser configuration.
+
+The name of the environment variable will be `PUT_<NAME>_SECRET`.
+If your instance is named `production`, you need to store the secret in the
+environment variable `PUT_PRODUCTION_SECRET`.
+The name will be transformed to uppercase.
+
+## Customization
+
+Of course, you can customize a lot of things:
+
+```yaml
+# .goreleaser.yml
+puts:
+  # You can have multiple Put instances.
+  -
+    # Unique name of your Put instance. Used to identify the instance.
+    name: production
+    # Upload mode. Valid options are `binary` and `archive`.
+    # If mode is `archive`, variables _Os_, _Arch_ and _Arm_ for target name are not supported.
+    # In that case these variables are empty.
+    # Default is `archive`.
+    mode: archive
+    # URL to be used as target of the HTTP PUT request
+    target: http://some.server/some/path/example-repo-local/{{ .ProjectName }}/{{ .Version }}/
+    # User that will be used for the deployment
+    username: deployuser
+```
+
+These settings should allow you to push your artifacts into multiple HTTP servers.