Move docs to ko.build

.github/workflows/publish-site.yaml

@@ -0,0 +1,16 @@
+name: publish
+on:
+  workflow_dispatch:
+  push:
+    branches: ['main']
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-python@v2
+        with:
+          python-version: 3.x
+      - run: pip install mkdocs-material 
+      - run: mkdocs gh-deploy --force

docs/README.md

@@ -0,0 +1,26 @@
+# Docs for https://ko.build
+
+## Development
+
+Update `.md` files to update content.
+
+Update `mkdocs.yml` to update sidebar headers and ordering.
+
+To run locally:
+
+- [install `mkdocs` and `mkdocs-material`](https://squidfunk.github.io/mkdocs-material/getting-started/) and run `mkdocs serve`, or
+- `docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material`
+  - on an M1 Mac, use `ghcr.io/afritzler/mkdocs-material` instead.
+
+This will start a local server on localhost:8000 that autoupdates as you make changes.
+
+## Deployment
+
+When PRs are merged, the site will be rebuilt and published automatically.
+
+### Credits
+
+The site is powered by [mkdocs-material](https://squidfunk.github.io/mkdocs-material). The code and theme are released under the MIT license.
+
+Content is licensed [CC-BY](https://creativecommons.org/licenses/by/4.0/).
+

docs/advanced/faq.md

@@ -0,0 +1,113 @@
+# Frequently Asked Questions
+
+## How can I set `ldflags`?
+
+[Using -ldflags](https://blog.cloudflare.com/setting-go-variables-at-compile-time/) is a common way to embed version info in go binaries (In fact, we do this for `ko`!).
+Unfortunately, because `ko` wraps `go build`, it's not possible to use this flag directly; however, you can use the `GOFLAGS` environment variable instead:
+
+```sh
+GOFLAGS="-ldflags=-X=main.version=1.2.3" ko build .
+```
+
+Currently, there is a limitation that does not allow to set multiple arguments in `ldflags` using `GOFLAGS`.
+Using `-ldflags` multiple times also does not work.
+In this use case, it works best to use the [`builds` section](./../configuration) in the `.ko.yaml` file.
+
+## Why are my images all created in 1970?
+
+In order to support [reproducible builds](https://reproducible-builds.org), `ko` doesn't embed timestamps in the images it produces by default.
+
+However, `ko` does respect the [`SOURCE_DATE_EPOCH`](https://reproducible-builds.org/docs/source-date-epoch/) environment variable, which will set the container image's timestamp accordingly.
+
+Similarly, the `KO_DATA_DATE_EPOCH` environment variable can be used to set the _modtime_ timestamp of the files in `KO_DATA_PATH`.
+
+For example, you can set the container image's timestamp to the current timestamp by executing:
+
+```sh
+export SOURCE_DATE_EPOCH=$(date +%s)
+```
+
+or set the timestamp of the files in `KO_DATA_PATH` to the latest git commit's timestamp with:
+
+```sh
+export KO_DATA_DATE_EPOCH=$(git log -1 --format='%ct')
+```
+
+## Can I build Windows containers?
+
+Yes, but support for Windows containers is new, experimental, and tenuous. Be prepared to file bugs. 🐛
+
+The default base image does not provide a Windows image.
+You can try out building a Windows container image by [setting the base image](./../configuration) to a Windows base image and building with `--platform=windows/amd64` or `--platform=all`:
+
+For example, to build a Windows container image, update your `.ko.yaml` to set the base image:
+
+```plaintext
+defaultBaseImage: mcr.microsoft.com/windows/nanoserver:ltsc2022
+```
+
+And build for `windows/amd64`.
+
+```sh
+ko build ./ --platform=windows/amd64
+```
+
+### Known issues 🐛
+
+- Symlinks in `kodata` are ignored when building Windows images; only regular files and directories will be included in the Windows image.
+
+## Can I optimize images for [eStargz support](https://github.com/containerd/stargz-snapshotter/blob/v0.7.0/docs/stargz-estargz.md)?
+
+Yes! Set the environment variable `GGCR_EXPERIMENT_ESTARGZ=1` to produce eStargz-optimized images.
+
+## Does `ko` support autocompletion?
+
+Yes! `ko completion` generates a Bash/Zsh/Fish/PowerShell completion script.
+You can get how to load it from help document.
+
+```sh
+ko completion [bash|zsh|fish|powershell] --help
+```
+
+Or, you can source it directly:
+
+```bash
+source <(ko completion)
+```
+
+## Does `ko` work with [Kustomize](https://kustomize.io/)?
+
+Yes! `ko resolve -f -` will read and process input from stdin, so you can have `ko` easily process the output of the `kustomize` command.
+
+```sh
+kustomize build config | ko resolve -f -
+```
+
+## Does `ko` integrate with other build and development tools?
+
+Oh, you betcha. Here's a partial list:
+
+- `ko` support in [Carvel's `kbld`](https://carvel.dev/kbld/docs/latest/config/#ko)
+- `ko` support in [Skaffold](https://skaffold.dev/docs/pipeline-stages/builders/ko/)
+- `ko` extension for [Tilt](https://github.com/tilt-dev/tilt-extensions/tree/master/ko)
+- `ko` support for [goreleaser](https://github.com/goreleaser/goreleaser/pull/2564) (proposed)
+
+## Does `ko` work with [OpenShift Internal Registry](https://docs.openshift.com/container-platform/latest/registry/registry-options.html#registry-integrated-openshift-registry_registry-options)?
+
+Yes! Follow these steps:
+
+1. [Connect to your OpenShift installation](https://docs.openshift.com/container-platform/latest/cli_reference/openshift_cli/getting-started-cli.html#cli-logging-in_cli-developer-commands)
+1. [Expose the OpenShift Internal Registry](https://docs.openshift.com/container-platform/latest/registry/securing-exposing-registry.html) so you can push to it:
+1. Export your token to `$HOME/.docker/config.json`:
+
+```sh
+oc registry login --to=$HOME/.docker/config.json
+```
+
+1. Create a namespace where you will push your images, i.e: `ko-images`
+1. Execute this command to set `KO_DOCKER_REPO` to publish images to the internal registry.
+
+```sh
+export KO_DOCKER_REPO=$(oc registry info --public)/ko-images
+```
+

docs/advanced/go-packages.md

@@ -0,0 +1,6 @@
+# Go Packages
+
+`ko`'s functionality can be consumed as a library in a Go application.
+
+To build an image, use [`pkg/build`](https://pkg.go.dev/github.com/google/ko/pkg/build), and publish it with [`pkg/publish`](https://pkg.go.dev/github.com/google/ko/pkg/publish).
+

docs/advanced/limitations.md

@@ -0,0 +1,12 @@
+# Limitations
+
+`ko` works best when your application has no dependencies on the underlying image.
+
+This means `ko` is ideal when you don't require [cgo](https://pkg.go.dev/cmd/cgo), and builds are executed with `CGO_ENABLED=0` by default.
+
+To install other OS packages, make those available in your [configured base image](./../configuration).
+
+`ko` only supports Go applications.
+For a similar tool targeting Java applications, try [Jib](https://github.com/GoogleContainerTools/jib).
+For other languages, try [apko](https://github.com/chainguard-dev/apko) and [melange](https://github.com/chainguard-dev/melange).
+

docs/advanced/migrating-from-dockerfile.md

@@ -0,0 +1,64 @@
+# Migrating from Dockerfile
+
+If your `Dockerfile` looks like either of the examples in the [official tutorial for writing a Dockerfile to containerize a Go application](https://docs.docker.com/language/golang/build-images/), you can easily migrate to use `ko` instead.
+
+Let's review the best practice multi-stage Dockerfile in that tutorial first:
+
+```plaintext
+# syntax=docker/dockerfile:1
+
+##
+## Build
+##
+FROM golang:1.16-buster AS build
+
+WORKDIR /app
+
+COPY go.mod ./
+COPY go.sum ./
+RUN go mod download
+
+COPY *.go ./
+
+RUN go build -o /docker-gs-ping
+
+##
+## Deploy
+##
+FROM gcr.io/distroless/base-debian10
+
+WORKDIR /
+
+COPY --from=build /docker-gs-ping /docker-gs-ping
+
+EXPOSE 8080
+
+USER nonroot:nonroot
+
+ENTRYPOINT ["/docker-gs-ping"]
+```
+
+This `Dockerfile`:
+
+1. pulls the `golang:1.16` image
+1. `COPY`s your local source into the container environment (`COPY`ing `go.mod` and `go.sum` first and running `go mod download`, to cache dependencies in the container environment)
+1. `RUN`s `go build` on your source, inside the container, to produce an executable
+1. `COPY`s the executable built in the previous step into a new image, on top of a minimal [distroless](https://github.com/GoogleContainerTools/distroless) base image.
+
+The result is a Go application built on a minimal base image, with an optimally cached build sequence.
+
+After running `docker build` on this `Dockerfile`, don't forget to push that image to the registry so you can deploy it.
+
+---
+
+## Migrating to `ko`
+
+If your Go source is laid out as described in the tutorial, and you've [installed](./../install) and [set up your environment](./../get-started), you can simply run `ko build ./` to build and push the container image to your registry.
+
+You're done. You can delete your `Dockerfile` and uninstall `docker`.
+
+`ko` takes advantage of your local [Go build cache](./../features/build-cache) without needing to be told to, and it sets the `ENTRYPOINT` and uses a nonroot distroless base image by default.
+
+To build a multi-arch image, simply add `--platform=all`.
+Compare this to the [equivalent Docker instructions](https://docs.docker.com/desktop/multi-arch/).
+

docs/configuration.md

@@ -0,0 +1,114 @@
+# Configuration
+
+## Basic Configuration
+
+Aside from `KO_DOCKER_REPO`, you can configure `ko`'s behavior using a
+`.ko.yaml` file. The location of this file can be overridden with
+`KO_CONFIG_PATH`.
+
+### Overriding Base Images
+
+By default, `ko` bases images on `gcr.io/distroless/static:nonroot`. This is a
+small image that provides the bare necessities to run your Go binary.
+
+You can override this base image in two ways:
+
+1. To override the base image for all images `ko` builds, add this line to your
+   `.ko.yaml` file:
+
+```yaml
+defaultBaseImage: registry.example.com/base/image
+```
+
+2. To override the base image for certain importpaths:
+
+```yaml
+baseImageOverrides:
+  github.com/my-user/my-repo/cmd/app: registry.example.com/base/for/app
+  github.com/my-user/my-repo/cmd/foo: registry.example.com/base/for/foo
+```
+
+### Overriding Go build settings
+
+By default, `ko` builds the binary with no additional build flags other than
+`-trimpath`. You can replace the default build
+arguments by providing build flags and ldflags using a
+[GoReleaser](https://github.com/goreleaser/goreleaser) influenced `builds`
+configuration section in your `.ko.yaml`.
+
+```yaml
+builds:
+- id: foo
+  dir: .  # default is .
+  main: ./foobar/foo
+  env:
+  - GOPRIVATE=git.internal.example.com,source.developers.google.com
+  flags:
+  - -tags
+  - netgo
+  ldflags:
+  - -s -w
+  - -extldflags "-static"
+  - -X main.version={{.Env.VERSION}}
+- id: bar
+  dir: ./bar
+  main: .  # default is .
+  env:
+  - GOCACHE=/workspace/.gocache
+  ldflags:
+  - -s
+  - -w
+```
+
+If your repository contains multiple modules (multiple `go.mod` files in
+different directories), use the `dir` field to specify the directory where
+`ko` should run `go build`.
+
+`ko` picks the entry from `builds` based on the import path you request. The
+import path is matched against the result of joining `dir` and `main`.
+
+The paths specified in `dir` and `main` are relative to the working directory
+of the `ko` process.
+
+The `ldflags` default value is `[]`.
+
+> 💡 **Note:** Even though the configuration section is similar to the
+[GoReleaser `builds` section](https://goreleaser.com/customization/build/),
+only the `env`, `flags` and `ldflags` fields are currently supported. Also, the
+templating support is currently limited to using environment variables only.
+
+## Naming Images
+
+`ko` provides a few different strategies for naming the image it pushes, to
+workaround certain registry limitations and user preferences:
+
+Given `KO_DOCKER_REPO=registry.example.com/repo`, by default,
+`ko build ./cmd/app` will produce an image named like
+`registry.example.com/repo/app-<md5>`, which includes the MD5 hash of the full
+import path, to avoid collisions.
+
+- `--preserve-import-path` (`-P`) will include the entire importpath:
+  `registry.example.com/repo/github.com/my-user/my-repo/cmd/app`
+- `--base-import-paths` (`-B`) will omit the MD5 portion:
+  `registry.example.com/repo/app`
+- `--bare` will only include the `KO_DOCKER_REPO`: `registry.example.com/repo`
+
+## Local Publishing Options
+
+`ko` is normally used to publish images to container image registries,
+identified by `KO_DOCKER_REPO`.
+
+`ko` can also load images to a local Docker daemon, if available, by setting
+`KO_DOCKER_REPO=ko.local`, or by passing the `--local` (`-L`) flag.
+
+Local images can be used as a base image for other `ko` images:
+
+```yaml
+defaultBaseImage: ko.local/example/base/image
+```
+
+`ko` can also load images into a local [KinD](https://kind.sigs.k8s.io)
+cluster, if available, by setting `KO_DOCKER_REPO=kind.local`. By default this
+loads into the default KinD cluster name (`kind`). To load into another KinD
+cluster, set `KIND_CLUSTER_NAME=my-other-cluster`.
+

docs/custom/main.html

@@ -0,0 +1,11 @@
+{% extends "base.html" %}
+
+{% block site_meta %}
+    {{ super() }}
+    {% if page and page.meta and page.meta.ko_meta %}
+    <meta charset=utf-8>
+    <meta name=go-import content="ko.build git https://github.com/ko-build/ko">
+    <meta name=go-source content="ko.build git https://github.com/ko-build/ko https://github.com/ko-build/ko/tree/main{/dir} https://github.com/ko-build/ko/blob/main{/dir}/{file}#L{line}">
+    {% endif %}
+{% endblock %}
+