diff --git a/docs/content/_index.md b/docs/content/_index.md index 9d81979b..1f0c82cf 100644 --- a/docs/content/_index.md +++ b/docs/content/_index.md @@ -43,7 +43,7 @@ We also run an experimental server for public use, so you can get started with A Here are some other ways to get involved: -- Read the full [walkthrough](/walkthrough) with setting up, running and testing the proxy +- Read the full [walkthrough](/walkthrough) with setting up, running and testing the Athens proxy explores this in greater depth. * Join our [weekly development meeting](/contributing/community/developer-meetings/)! It's a great way to meet folks working on the project, ask questions or just hang out. All are welcome to join and participate. * Check out our issue queue for [good first issues](https://github.com/gomods/athens/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) diff --git a/docs/content/configuration/authentication.md b/docs/content/configuration/authentication.md index d10d1ee5..4b607ab0 100644 --- a/docs/content/configuration/authentication.md +++ b/docs/content/configuration/authentication.md @@ -19,7 +19,7 @@ weight: 1 Username: test Password for 'test': -3. Once we've properly authenticated we want to share the .subversion directory with the proxy server in order to reuse those credentials. Below we're setting it as a volume on our proxy container. +3. Once we've properly authenticated we want to share the .subversion directory with the Athens proxy server in order to reuse those credentials. Below we're setting it as a volume on our proxy container. **Bash** @@ -142,7 +142,7 @@ weight: 1 user=proxyuser1 password=proxypass1 -5. Once we've properly setup our authentication we want to share the bazaar configuration directory with the proxy server in order to reuse those credentials. Below we're setting it as a volume on our proxy container. +5. Once we've properly setup our authentication we want to share the bazaar configuration directory with the Athens proxy server in order to reuse those credentials. Below we're setting it as a volume on our proxy container. **Bash** diff --git a/docs/content/design/_index.md b/docs/content/design/_index.md index 79ea7a0b..643b1756 100644 --- a/docs/content/design/_index.md +++ b/docs/content/design/_index.md @@ -10,8 +10,8 @@ This section of the documentation details the design of Athens. You can read the We've split this section into two major sections: -1. [Proxy internals](./proxy) - basics of the proxy architecture and major features -2. [Communication flow](./communication) - how the proxy interacts with the outside world to fetch and store code, respond to user requests, and so on +1. [Proxy internals](./proxy) - basics of the Athens proxy architecture and major features +2. [Communication flow](./communication) - how the Athens proxy interacts with the outside world to fetch and store code, respond to user requests, and so on ## How to Read this Section diff --git a/docs/content/design/communication.md b/docs/content/design/communication.md index 981c9764..81ce47d2 100644 --- a/docs/content/design/communication.md +++ b/docs/content/design/communication.md @@ -10,14 +10,14 @@ Only one project dared to challenge their power...Athens. Athens possessed a str ### Clean plate -At the beginning, there's theoretical state when a storage of the proxy is empty. +At the beginning, there's theoretical state when a storage of the Athens proxy is empty. When User makes a request at this ancient time, it works as described on the flow below. - User runs `go get` to acquire new module. -- Go CLI contacts the proxy asking for module M, version v1.0 -- The proxy checks whether or not it has this module in its storage. It does not. -- The proxy downloads code from the underlying VCS and converts it into the Go Module format. +- Go CLI contacts the Athens proxy asking for module M, version v1.0 +- The Athens proxy checks whether or not it has this module in its storage. It does not. +- The Athens proxy downloads code from the underlying VCS and converts it into the Go Module format. - After it receives all the bits, it stores it into its own storage and serves it to the User. - User receives module and is happy. @@ -27,6 +27,6 @@ The process from the user using `go get` all the way to the user downloading a m ### Happy path -Now that the proxy is aware of module M at version v1.0, it can serve that module immediately to the user, without fetching it from the VCS. +Now that the Athens proxy is aware of module M at version v1.0, it can serve that module immediately to the user, without fetching it from the VCS. ![Communication flow for new proxy](/athens-proxy-filled.png) diff --git a/docs/content/design/proxy.md b/docs/content/design/proxy.md index 8d9d4974..cf18bbc9 100644 --- a/docs/content/design/proxy.md +++ b/docs/content/design/proxy.md @@ -5,14 +5,14 @@ date: 2018-02-11T15:59:56-05:00 ## The Athens Proxy -The proxy has two primary use cases: +The Athens proxy has two primary use cases: - Internal deployments - Public mirror deployments -This document details features of the proxy that you can use to achieve either use case. +This document details features of the Athens proxy that you can use to achieve either use case. -## The Role of the Proxy +## The Role of the Athens proxy We intend proxies to be deployed primarily inside of enterprises to: @@ -24,11 +24,11 @@ Importantly, a proxy is not intended to be a complete _mirror_ of an upstream pr ## Cache Misses -When a user requests a module `MxV1` from a proxy and the proxy doesn't have `MxV1` in its cache, it first determines whether `MxV1` is private or not private. +When a user requests a module `MxV1` from a proxy and the Athens proxy doesn't have `MxV1` in its cache, it first determines whether `MxV1` is private or not private. If it's private, it immediately does a cache fill operation from the internal VCS. -If it's not private, the proxy consults its exclude list for non-private modules (see below). If `MxV1` is on the exclude list, the proxy returns 404 and does nothing else. If `MxV1` is not on the exclude list, the proxy executes the following algorithm: +If it's not private, the Athens proxy consults its exclude list for non-private modules (see below). If `MxV1` is on the exclude list, the Athens proxy returns 404 and does nothing else. If `MxV1` is not on the exclude list, the Athens proxy executes the following algorithm: ``` upstreamDetails := lookUpstream(MxV1) @@ -47,18 +47,18 @@ _In a later version of the project, we may implement an event stream on proxies ## Exclude Lists and Private Module Filters -To accommodate private (i.e. enterprise) deployments, the proxy maintains two important access control mechanisms: +To accommodate private (i.e. enterprise) deployments, the Athens proxy maintains two important access control mechanisms: - Private module filters - Exclude lists for public modules ### Private Module Filters -Private module filters are string globs that tell the proxy what is a private module. For example, the string `github.internal.com/**` tells the proxy: +Private module filters are string globs that tell the Athens proxy what is a private module. For example, the string `github.internal.com/**` tells the Athens proxy: - To never make requests to the public internet (i.e. to upstream proxies) regarding this module - To download module code (in its cache filling mechanism) from the VCS at `github.internal.com` ### Exclude Lists for Public Modules -Exclude lists for public modules are also globs that tell the proxy what modules it should never download from any upstream proxy. For example, the string `github.com/arschles/**` tells the proxy to always return `404 Not Found` to clients. +Exclude lists for public modules are also globs that tell the Athens proxy what modules it should never download from any upstream proxy. For example, the string `github.com/arschles/**` tells the Athens proxy to always return `404 Not Found` to clients. diff --git a/docs/content/faq.md b/docs/content/faq.md index 8881e05b..27e88892 100644 --- a/docs/content/faq.md +++ b/docs/content/faq.md @@ -12,7 +12,7 @@ A registry is generally run by one entity, is one logical server that provides a That's most definitely not what we in the Athens community are going for, and that would harm our community if we did go down that path. -First and foremost, Athens is an _implementation_ of the [Go Modules download API](./intro/protocol). Not only does the standard Go toolchain support any implementation of that API, the proxy is designed to talk to any other server that implements that API as well. That allows Athens to talk to other proxies in the community. +First and foremost, Athens is an _implementation_ of the [Go Modules download API](./intro/protocol). Not only does the standard Go toolchain support any implementation of that API, the Athens proxy is designed to talk to any other server that implements that API as well. That allows Athens to talk to other proxies in the community. Finally, we're purposefully building this project - and working with the toolchain folks - in a way that everyone who wants to write a proxy can participate. @@ -42,7 +42,7 @@ To repeat, "datastore" means a CDN (we currently have support for Google Cloud S One final note - we use "caching" in lots of our docs, and that's technically wrong because no data is evicted or expires. We'll need to update that terminology. -### Can the proxy authenticate to private repositories? +### Can the Athens proxy authenticate to private repositories? _TL;DR: yes, with proper authentication configuration defined on the Athens proxy host._ @@ -67,5 +67,5 @@ To try out tracing with Jaeger, do the following: - Run the walkthrough tutorial - Open `http://localhost:16686/search` -Observability is not a hard requirement for the proxy. So, if the infrastructure is not properly set up, they will fail with an information log. For eg. if Jaeger is not running / if the wrong URL to the exporter is provided, proxy will continue to run. However, it will not collect any traces or metrics (when the exporter backend is unavailable). +Observability is not a hard requirement for the Athens proxy. So, if the infrastructure is not properly set up, they will fail with an information log. For eg. if Jaeger is not running / if the wrong URL to the exporter is provided, proxy will continue to run. However, it will not collect any traces or metrics (when the exporter backend is unavailable). diff --git a/docs/content/install/install-on-kubernetes.md b/docs/content/install/install-on-kubernetes.md index df1014b8..eab6eb9f 100644 --- a/docs/content/install/install-on-kubernetes.md +++ b/docs/content/install/install-on-kubernetes.md @@ -4,7 +4,7 @@ description: Installing an Athens Instance on Kubernetes weight: 1 --- -When you follow the instructions in the [Walkthrough](/walkthrough), you end up with an Athens Proxy that uses in-memory storage. This is only suitable for trying out the proxy for a short period of time, as you will quickly run out of memory and Athens won't persist modules between restarts. In order to run a more production-like proxy, you may with to run Athens on a [Kubernetes](https://kubernetes.io/) cluster. To aid in deployment of the Athens proxy on Kubernetes, a [Helm](https://www.helm.sh/) chart has been provided. This guide will walk you through installing Athens on a Kubernetes cluster using Helm. +When you follow the instructions in the [Walkthrough](/walkthrough), you end up with an Athens Proxy that uses in-memory storage. This is only suitable for trying out the Athens proxy for a short period of time, as you will quickly run out of memory and Athens won't persist modules between restarts. In order to run a more production-like proxy, you may with to run Athens on a [Kubernetes](https://kubernetes.io/) cluster. To aid in deployment of the Athens proxy on Kubernetes, a [Helm](https://www.helm.sh/) chart has been provided. This guide will walk you through installing Athens on a Kubernetes cluster using Helm. * [Prerequisites](#prerequisites) * [Configure Helm](#configure-helm) @@ -91,7 +91,7 @@ This will deploy a single Athens instance in the `default` namespace with `disk` ### Give Athens access to private repositories via Github Token (Optional) 1. Create a token at https://github.com/settings/tokens -2. Provide the token to the proxy either through the config.toml file or by setting the `ATHENS_GITHUB_TOKEN` environment variable. +2. Provide the token to the Athens proxy either through the config.toml file or by setting the `ATHENS_GITHUB_TOKEN` environment variable. ### Storage Providers @@ -121,7 +121,7 @@ helm install ./charts/proxy -n athens --set storage.type=mongo --set storage.mon ### Kuberentes Service -By default, a Kubernetes `ClusterIP` service is created for the Athens proxy. "ClusterIP" is sufficient in the case when the Proxy will be used from within the cluster. To expose Athens outside of the cluster, consider using a "NodePort" or "LoadBalancer" service. This can be changed by setting the `service.type` value when installing the chart. For example, to deploy Athens using a NodePort service, the following command could be used: +By default, a Kubernetes `ClusterIP` service is created for the Athens proxy. "ClusterIP" is sufficient in the case when the Athens proxy will be used from within the cluster. To expose Athens outside of the cluster, consider using a "NodePort" or "LoadBalancer" service. This can be changed by setting the `service.type` value when installing the chart. For example, to deploy Athens using a NodePort service, the following command could be used: ```console helm install ./charts/proxy -n athens --set service.type=NodePort diff --git a/docs/content/install/shared-team-instance.md b/docs/content/install/shared-team-instance.md index 1fffe00a..cb29fed1 100644 --- a/docs/content/install/shared-team-instance.md +++ b/docs/content/install/shared-team-instance.md @@ -4,7 +4,7 @@ description: Installing an Athens Instance For Your Development Team weight: 2 --- -When you follow the instructions in the [Walkthrough](/walkthrough), you end up with an Athens Proxy that uses in-memory storage. This is only suitable for trying out the proxy for a short period of time, as you will quickly run out of memory and Athens won't persist modules between restarts. This guide will help you get Athens running in a more suitable manner for scenarios like providing an instance for your development team to share. +When you follow the instructions in the [Walkthrough](/walkthrough), you end up with an Athens Proxy that uses in-memory storage. This is only suitable for trying out the Athens proxy for a short period of time, as you will quickly run out of memory and Athens won't persist modules between restarts. This guide will help you get Athens running in a more suitable manner for scenarios like providing an instance for your development team to share. We will use Docker to run the Athens proxy, so first make sure you have Docker [installed](https://docs.docker.com/install/). diff --git a/docs/content/try-out.md b/docs/content/try-out.md index 33ba43ee..c59e3bc3 100644 --- a/docs/content/try-out.md +++ b/docs/content/try-out.md @@ -34,7 +34,7 @@ INFO[0000] Exporter not specified. Traces won't be exported INFO[0000] Starting application at http://127.0.0.1:3000 ``` -Next, you will need to configure Go to use the proxy! +Next, you will need to configure Go to use the Athens proxy! **Bash** ```bash diff --git a/docs/content/walkthrough.md b/docs/content/walkthrough.md index 4c2d4757..615c7e48 100644 --- a/docs/content/walkthrough.md +++ b/docs/content/walkthrough.md @@ -6,8 +6,8 @@ menu: shortcuts First, make sure you have [Go 1.11 installed](https://gophersource.com/setup/) and that GOPATH/bin is on your path. -## Without the proxy -Let's review what everything looks like in Go 1.11 without the proxy in the picture: +## Without the Athens proxy +Let's review what everything looks like in Go 1.11 without the Athens proxy in the picture: **Bash** ```console @@ -31,14 +31,14 @@ The 🦁 says rawr! The end result of running this command is that Go downloaded the package source and packaged it into a module, saving it in the Go Modules cache. -Now that we have seen Go Modules in action without the proxy, let's take a look at -how the proxy changes the workflow and the output. +Now that we have seen Go Modules in action without the Athens proxy, let's take a look at +how the Athens proxy changes the workflow and the output. -## With the proxy +## With the Athens proxy Using the most simple installation possible, let's walk through how to use the Athens proxy, and figure out what is happening at each step. -Before moving on, let's clear our Go Modules cache so that we can see the proxy +Before moving on, let's clear our Go Modules cache so that we can see the Athens proxy in action without any caches populated: **Bash** @@ -82,7 +82,7 @@ The Athens proxy is now running in the background and is listening for requests from localhost (127.0.0.1) on port 3000. Since we didn't provide any specific configuration -the proxy is using in-memory storage, which is only suitable for trying out the proxy +the Athens proxy is using in-memory storage, which is only suitable for trying out the Athens proxy for a short period of time, as you will quickly run out of memory and the storage doesn't persist between restarts. @@ -118,9 +118,9 @@ docker run -d -v "$($env:ATHENS-STORAGE):/var/lib/athens" ` ``` Next, you will need to enable the [Go Modules](https://github.com/golang/go/wiki/Modules) -feature and configure Go to use the proxy! +feature and configure Go to use the Athens proxy! -### Using the proxy +### Using the Athens proxy **Bash** ```bash export GO111MODULE=on @@ -142,7 +142,7 @@ Possible values are: The `GOPROXY` environment variable tells the `go` binary that instead of talking to the version control system, such as github.com, directly when resolving your package -dependencies, instead it should communicate with a proxy. The proxy implements +dependencies, instead it should communicate with a proxy. The Athens proxy implements the [Go Download Protocol](/intro/protocol), and is responsible for listing available versions for a package in addition to providing a zip of particular package versions. @@ -181,7 +181,7 @@ Let's break down what is happening here: running this, our cache is empty and Go keeps looking. 1. Go requests **github.com/athens-artifacts/samplelib@v1.0.0** from our proxy because it is set in the GOPROXY environment variable. -1. The proxy checks its own storage (in this case is in-memory) for the package and doesn't find it. So it +1. The Athens proxy checks its own storage (in this case is in-memory) for the package and doesn't find it. So it retrieves it from github.com and then saves it for subsequent requests. 1. Go downloads the module zip and puts it in the Go Modules cache GOPATH/pkg/mod. @@ -195,9 +195,9 @@ The 🦁 says rawr! ``` No additional output is printed because Go found **github.com/athens-artifacts/samplelib@v1.0.0** in the Go Module -cache and did not need to request it from the proxy. +cache and did not need to request it from the Athens proxy. -Lastly, quitting from the proxy. This cannot be done directly because we are starting the proxy in the background, thus we must kill it by finding it's process ID and killing it manually. +Lastly, quitting from the Athens proxy. This cannot be done directly because we are starting the Athens proxy in the background, thus we must kill it by finding it's process ID and killing it manually. **Bash** ```bash