TrueCloudLab/distribution
13
0
Fork 3
Code Issues 3 Pull requests Projects Releases 2 Packages Wiki Activity Actions

docs: fix broken links and improve link resolution

Browse source 
Update the formatting of links and add a Markdown render hook for
handling relative internal links. Cross-references between markdown
files are now resolved the same way in both GitHub and Hugo.

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
This commit is contained in:
David Karlsson 2024-01-09 20:10:18 +01:00
parent 1d2895f2bf
commit 5e75227fb2
20 changed files with 64 additions and 64 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
.github/workflows/docs.yml vendored
View file

@ -38,8 +38,6 @@ jobs:
set: | set: |
*.cache-from=type=gha,scope=docs *.cache-from=type=gha,scope=docs
*.cache-to=type=gha,scope=docs,mode=max *.cache-to=type=gha,scope=docs,mode=max
env:
DOCS_BASEURL: ${{ steps.pages.outputs.base_path }}
- name: Fix permissions - name: Fix permissions
run: | run: |
chmod -c -R +rX "./build/docs" | while read line; do chmod -c -R +rX "./build/docs" | while read line; do

7
docker-bake.hcl
View file

@ -91,15 +91,8 @@ target "image-all" {
] ]
} }
variable "DOCS_BASEURL" {
default = null
}
target "_common_docs" { target "_common_docs" {
dockerfile = "./dockerfiles/docs.Dockerfile" dockerfile = "./dockerfiles/docs.Dockerfile"
args = {
DOCS_BASEURL = DOCS_BASEURL
}
} }
target "docs-export" { target "docs-export" {

9
dockerfiles/docs.Dockerfile
View file

@ -16,9 +16,8 @@ COPY --from=hugo $GOPATH/bin/hugo /bin/hugo
WORKDIR /src WORKDIR /src
FROM build-base AS build FROM build-base AS build
ARG DOCS_BASEURL=/
RUN --mount=type=bind,rw,source=docs,target=. \ RUN --mount=type=bind,rw,source=docs,target=. \
hugo --gc --minify --destination /out -b $DOCS_BASEURL hugo --gc --minify --destination /out
FROM build-base AS server FROM build-base AS server
COPY docs . COPY docs .
@ -29,8 +28,12 @@ FROM scratch AS out
COPY --from=build /out / COPY --from=build /out /
FROM wjdp/htmltest:v0.17.0 AS test FROM wjdp/htmltest:v0.17.0 AS test
# Copy the site to a public/distribution subdirectory
# This is a workaround for a limitation in htmltest, see:
# https://github.com/wjdp/htmltest/issues/45
WORKDIR /test/public/distribution
COPY --from=build /out .
WORKDIR /test WORKDIR /test
COPY --from=build /out ./public
ADD docs/.htmltest.yml .htmltest.yml ADD docs/.htmltest.yml .htmltest.yml
RUN --mount=type=cache,target=tmp/.htmltest \ RUN --mount=type=cache,target=tmp/.htmltest \
htmltest htmltest

20
docs/content/about/configuration.md
View file

@ -434,17 +434,17 @@ The `storage` option is **required** and defines which storage backend is in
use. You must configure exactly one backend. If you configure more, the registry use. You must configure exactly one backend. If you configure more, the registry
returns an error. You can choose any of these backend storage drivers: returns an error. You can choose any of these backend storage drivers:
| Storage driver | Description | | Storage driver | Description |
|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `filesystem` | Uses the local disk to store registry files. It is ideal for development and may be appropriate for some small-scale production applications. See the [driver's reference documentation](/storage-drivers/filesystem). | | `filesystem` | Uses the local disk to store registry files. It is ideal for development and may be appropriate for some small-scale production applications. See the [driver's reference documentation](../storage-drivers/filesystem.md). |
| `azure` | Uses Microsoft Azure Blob Storage. See the [driver's reference documentation](/storage-drivers/azure). | | `azure` | Uses Microsoft Azure Blob Storage. See the [driver's reference documentation](../storage-drivers/azure.md). |
| `gcs` | Uses Google Cloud Storage. See the [driver's reference documentation](/storage-drivers/gcs). | | `gcs` | Uses Google Cloud Storage. See the [driver's reference documentation](../storage-drivers/gcs.md). |
| `s3` | Uses Amazon Simple Storage Service (S3) and compatible Storage Services. See the [driver's reference documentation](/storage-drivers/s3). | | `s3` | Uses Amazon Simple Storage Service (S3) and compatible Storage Services. See the [driver's reference documentation](../storage-drivers/s3.md). |
For testing only, you can use the [`inmemory` storage For testing only, you can use the [`inmemory` storage
driver](/storage-drivers/inmemory). driver](../storage-drivers/inmemory.md).
If you would like to run a registry from volatile memory, use the If you would like to run a registry from volatile memory, use the
[`filesystem` driver](/storage-drivers/filesystem) [`filesystem` driver](../storage-drivers/filesystem.md)
on a ramdisk. on a ramdisk.
If you are deploying a registry on Windows, a Windows volume mounted from the If you are deploying a registry on Windows, a Windows volume mounted from the
@ -593,7 +593,7 @@ security.
For more information about Token based authentication configuration, see the For more information about Token based authentication configuration, see the
[specification](/spec/auth/token). [specification](../spec/auth/token.md).
### `htpasswd` ### `htpasswd`
@ -1100,7 +1100,7 @@ proxy:
The `proxy` structure allows a registry to be configured as a pull-through cache The `proxy` structure allows a registry to be configured as a pull-through cache
to Docker Hub. See to Docker Hub. See
[mirror](/recipes/mirror) [mirror](../recipes/mirror.md)
for more information. Pushing to a registry configured as a pull-through cache for more information. Pushing to a registry configured as a pull-through cache
is unsupported. is unsupported.

34
docs/content/about/deploying.md
View file

@ -9,7 +9,7 @@ A registry is an instance of the `registry` image, and runs within Docker.
This topic provides basic information about deploying and configuring a This topic provides basic information about deploying and configuring a
registry. For an exhaustive list of configuration options, see the registry. For an exhaustive list of configuration options, see the
[configuration reference](../configuration). [configuration reference](configuration.md).
If you have an air-gapped datacenter, see If you have an air-gapped datacenter, see
[Considerations for air-gapped registries](#considerations-for-air-gapped-registries). [Considerations for air-gapped registries](#considerations-for-air-gapped-registries).
@ -27,7 +27,7 @@ The registry is now ready to use.
> **Warning**: These first few examples show registry configurations that are > **Warning**: These first few examples show registry configurations that are
> only appropriate for testing. A production-ready registry must be protected by > only appropriate for testing. A production-ready registry must be protected by
> TLS and should ideally use an access-control mechanism. Keep reading and then > TLS and should ideally use an access-control mechanism. Keep reading and then
> continue to the [configuration guide](../configuration) to deploy a > continue to the [configuration guide](configuration.md) to deploy a
> production-ready registry. > production-ready registry.
## Copy an image from Docker Hub to your registry ## Copy an image from Docker Hub to your registry
@ -94,7 +94,7 @@ To configure the container, you can pass additional or modified options to the
`docker run` command. `docker run` command.
The following sections provide basic guidelines for configuring your registry. The following sections provide basic guidelines for configuring your registry.
For more details, see the [registry configuration reference](../configuration). For more details, see the [registry configuration reference](configuration.md).
### Start the registry automatically ### Start the registry automatically
@ -166,8 +166,8 @@ $ docker run -d \
By default, the registry stores its data on the local filesystem, whether you By default, the registry stores its data on the local filesystem, whether you
use a bind mount or a volume. You can store the registry data in an Amazon S3 use a bind mount or a volume. You can store the registry data in an Amazon S3
bucket, Google Cloud Platform, or on another storage back-end by using bucket, Google Cloud Platform, or on another storage back-end by using
[storage drivers](/storage-drivers). For more information, see [storage drivers](../storage-drivers/_index.md). For more information, see
[storage configuration options](../configuration#storage). [storage configuration options](configuration.md#storage).
## Run an externally-accessible registry ## Run an externally-accessible registry
@ -252,13 +252,13 @@ The registry supports using Let's Encrypt to automatically obtain a
browser-trusted certificate. For more information on Let's Encrypt, see browser-trusted certificate. For more information on Let's Encrypt, see
[https://letsencrypt.org/how-it-works/](https://letsencrypt.org/how-it-works/) [https://letsencrypt.org/how-it-works/](https://letsencrypt.org/how-it-works/)
and the relevant section of the and the relevant section of the
[registry configuration](../configuration#letsencrypt). [registry configuration](configuration.md#letsencrypt).
### Use an insecure registry (testing only) ### Use an insecure registry (testing only)
It is possible to use a self-signed certificate, or to use our registry It is possible to use a self-signed certificate, or to use our registry
insecurely. Unless you have set up verification for your self-signed insecurely. Unless you have set up verification for your self-signed
certificate, this is for testing only. See [run an insecure registry](../insecure). certificate, this is for testing only. See [run an insecure registry](insecure.md).
## Run the registry as a service ## Run the registry as a service
@ -462,20 +462,20 @@ using htpasswd, all authentication attempts will fail.
{{< hint type=note title="X509 errors" >}} {{< hint type=note title="X509 errors" >}}
X509 errors usually indicate that you are attempting to use X509 errors usually indicate that you are attempting to use
a self-signed certificate without configuring the Docker daemon correctly. a self-signed certificate without configuring the Docker daemon correctly.
See [run an insecure registry](../insecure). See [run an insecure registry](insecure.md).
{{< /hint >}} {{< /hint >}}
### More advanced authentication ### More advanced authentication
You may want to leverage more advanced basic auth implementations by using a You may want to leverage more advanced basic auth implementations by using a
proxy in front of the registry. See the [recipes list](/recipes/). proxy in front of the registry. See the [recipes list](../recipes/_index.md).
The registry also supports delegated authentication which redirects users to a The registry also supports delegated authentication which redirects users to a
specific trusted token server. This approach is more complicated to set up, and specific trusted token server. This approach is more complicated to set up, and
only makes sense if you need to fully configure ACLs and need more control over only makes sense if you need to fully configure ACLs and need more control over
the registry's integration into your global authorization and authentication the registry's integration into your global authorization and authentication
systems. Refer to the following [background information](/spec/auth/token) and systems. Refer to the following [background information](../spec/auth/token.md) and
[configuration information here](../configuration#auth). [configuration information here](configuration.md#auth).
This approach requires you to implement your own authentication system or This approach requires you to implement your own authentication system or
leverage a third-party implementation. leverage a third-party implementation.
@ -572,9 +572,9 @@ artifacts.
More specific and advanced information is available in the following sections: More specific and advanced information is available in the following sections:
- [Configuration reference](../configuration) - [Configuration reference](configuration.md)
- [Working with notifications](../notifications) - [Working with notifications](notifications.md)
- [Advanced "recipes"](/recipes) - [Advanced "recipes"](../recipes/_index.md)
- [Registry API](/spec/api) - [Registry API](../spec/api.md)
- [Storage driver model](/storage-drivers) - [Storage driver model](../storage-drivers/_index.md)
- [Token authentication](/spec/auth/token) - [Token authentication](../spec/auth/token.md)

6
docs/content/about/garbage-collection.md
View file

@ -21,15 +21,15 @@ that certain layers no longer exist on the filesystem.
Filesystem layers are stored by their content address in the Registry. This Filesystem layers are stored by their content address in the Registry. This
has many advantages, one of which is that data is stored once and referred to by manifests. has many advantages, one of which is that data is stored once and referred to by manifests.
See [here](../compatibility#content-addressable-storage-cas) for more details. See [here](compatibility.md#content-addressable-storage-cas) for more details.
Layers are therefore shared amongst manifests; each manifest maintains a reference Layers are therefore shared amongst manifests; each manifest maintains a reference
to the layer. As long as a layer is referenced by one manifest, it cannot be garbage to the layer. As long as a layer is referenced by one manifest, it cannot be garbage
collected. collected.
Manifests and layers can be `deleted` with the registry API (refer to the API Manifests and layers can be `deleted` with the registry API (refer to the API
documentation [here](/spec/api#deleting-a-layer) and documentation [here](../spec/api.md#deleting-a-layer) and
[here](/spec/api#deleting-an-image) for details). This API removes references [here](../spec/api.md#deleting-an-image) for details). This API removes references
to the target and makes them eligible for garbage collection. It also makes them to the target and makes them eligible for garbage collection. It also makes them
unable to be read via the API. unable to be read via the API.

2
docs/content/about/insecure.md
View file

@ -72,7 +72,7 @@ This is more secure than the insecure registry solution.
Be sure to use the name `myregistry.domain.com` as a CN. Be sure to use the name `myregistry.domain.com` as a CN.
2. Use the result to [start your registry with TLS enabled](../deploying#get-a-certificate). 2. Use the result to [start your registry with TLS enabled](deploying.md#get-a-certificate).
3. Instruct every Docker daemon to trust that certificate. The way to do this 3. Instruct every Docker daemon to trust that certificate. The way to do this
depends on your OS. depends on your OS.

4
docs/content/about/notifications.md
View file

@ -10,7 +10,7 @@ pushes and pulls and layer pushes and pulls. These actions are serialized into
events. The events are queued into a registry-internal broadcast system which events. The events are queued into a registry-internal broadcast system which
queues and dispatches events to [_Endpoints_](#endpoints). queues and dispatches events to [_Endpoints_](#endpoints).
![Workflow of registry notifications](../../images/notifications.png) ![Workflow of registry notifications](/distribution/images/notifications.png)
## Endpoints ## Endpoints
@ -45,7 +45,7 @@ The above would configure the registry with an endpoint to send events to
5 failures happen consecutively, the registry backs off for 1 second before 5 failures happen consecutively, the registry backs off for 1 second before
trying again. trying again.
For details on the fields, see the [configuration documentation](../configuration/#notifications). For details on the fields, see the [configuration documentation](configuration.md#notifications).
A properly configured endpoint should lead to a log message from the registry A properly configured endpoint should lead to a log message from the registry
upon startup: upon startup:

2
docs/content/recipes/apache.md
View file

@ -12,7 +12,7 @@ Usually, that includes enterprise setups using LDAP/AD on the backend and a SSO
### Alternatives ### Alternatives
If you just want authentication for your registry, and are happy maintaining users access separately, you should really consider sticking with the native [basic auth registry feature](/about/deploying#native-basic-auth). If you just want authentication for your registry, and are happy maintaining users access separately, you should really consider sticking with the native [basic auth registry feature](../about/deploying.md#native-basic-auth).
### Solution ### Solution

2
docs/content/recipes/mirror.md
View file

@ -107,7 +107,7 @@ proxy:
> **Warning**: For the scheduler to clean up old entries, `delete` must > **Warning**: For the scheduler to clean up old entries, `delete` must
> be enabled in the registry configuration. See > be enabled in the registry configuration. See
> [Registry Configuration](/about/configuration) for more details. > [Registry Configuration](../about/configuration.md) for more details.
### Configure the Docker daemon ### Configure the Docker daemon

2
docs/content/recipes/nginx.md
View file

@ -17,7 +17,7 @@ mechanism fronting their internal http portal.
If you just want authentication for your registry, and are happy maintaining If you just want authentication for your registry, and are happy maintaining
users access separately, you should really consider sticking with the native users access separately, you should really consider sticking with the native
[basic auth registry feature](/about/deploying#native-basic-auth). [basic auth registry feature](../about/deploying.md#native-basic-auth).
### Solution ### Solution

8
docs/content/spec/_index.md
View file

@ -6,7 +6,7 @@ keywords: registry, service, images, repository, json
# Docker Registry Reference # Docker Registry Reference
* [HTTP API V2](api) * [HTTP API V2](api.md)
* [Storage Driver](/storage-drivers/) * [Storage Driver](../storage-drivers/_index.md)
* [Token Authentication Specification](auth/token) * [Token Authentication Specification](auth/token.md)
* [Token Authentication Implementation](auth/jwt) * [Token Authentication Implementation](auth/jwt.md)

6
docs/content/spec/api.md
View file

@ -416,7 +416,7 @@ reference may include a tag or digest.
The client should include an Accept header indicating which manifest content The client should include an Accept header indicating which manifest content
types it supports. For more details on the manifest format and content types, types it supports. For more details on the manifest format and content types,
see [Image Manifest Version 2, Schema 2](../manifest-v2-2). see [Image Manifest Version 2, Schema 2](manifest-v2-2.md).
In a successful response, the Content-Type header will indicate which manifest type is being returned. In a successful response, the Content-Type header will indicate which manifest type is being returned.
A `404 Not Found` response will be returned if the image is unknown to the A `404 Not Found` response will be returned if the image is unknown to the
@ -840,7 +840,7 @@ Content-Type: <manifest media type>
The `name` and `reference` fields of the response body must match those The `name` and `reference` fields of the response body must match those
specified in the URL. The `reference` field may be a "tag" or a "digest". The specified in the URL. The `reference` field may be a "tag" or a "digest". The
content type should match the type of the manifest being uploaded, as specified content type should match the type of the manifest being uploaded, as specified
in [Image Manifest Version 2, Schema 2](../manifest-v2-2). in [Image Manifest Version 2, Schema 2](manifest-v2-2.md).
If there is a problem with pushing the manifest, a relevant 4xx response will If there is a problem with pushing the manifest, a relevant 4xx response will
be returned with a JSON error message. Please see the be returned with a JSON error message. Please see the
@ -1088,7 +1088,7 @@ response will be issued instead.
Accept: application/vnd.docker.distribution.manifest.v2+json Accept: application/vnd.docker.distribution.manifest.v2+json
> for more details, see: [compatibility](/about/compatibility#content-addressable-storage-cas) > for more details, see: [compatibility](../about/compatibility.md#content-addressable-storage-cas)
## Detail ## Detail

2
docs/content/spec/auth/oauth.md
View file

@ -12,7 +12,7 @@ reference for the protocol and HTTP endpoints described here.
**Note**: Not all token servers implement oauth2. If the request to the endpoint **Note**: Not all token servers implement oauth2. If the request to the endpoint
returns `404` using the HTTP `POST` method, refer to returns `404` using the HTTP `POST` method, refer to
[Token Documentation](../token) for using the HTTP `GET` method supported by all [Token Documentation](token.md) for using the HTTP `GET` method supported by all
token servers. token servers.
## Refresh token format ## Refresh token format

2
docs/content/spec/auth/scope.md
View file

@ -144,7 +144,7 @@ Each JWT access token may only have a single subject and audience but multiple
resource scopes. The subject and audience are put into standard JWT fields resource scopes. The subject and audience are put into standard JWT fields
`sub` and `aud`. The resource scope is put into the `access` field. The `sub` and `aud`. The resource scope is put into the `access` field. The
structure of the access field can be seen in the structure of the access field can be seen in the
[jwt documentation](../jwt). [jwt documentation](jwt.md).
## Refresh Tokens ## Refresh Tokens

4
docs/content/spec/auth/token.md
View file

@ -8,7 +8,7 @@ keywords: registry, on-prem, images, tags, repository, distribution, Bearer auth
This document outlines the v2 Distribution registry authentication scheme: This document outlines the v2 Distribution registry authentication scheme:
![v2 registry auth](../../../images/v2-registry-auth.png) ![v2 registry auth](/distribution/images/v2-registry-auth.png)
1. Attempt to begin a push/pull operation with the registry. 1. Attempt to begin a push/pull operation with the registry.
2. If the registry requires authorization it will return a `401 Unauthorized` 2. If the registry requires authorization it will return a `401 Unauthorized`
@ -188,7 +188,7 @@ https://auth.docker.io/token?service=registry.docker.io&scope=repository:samalba
The token server should first attempt to authenticate the client using any The token server should first attempt to authenticate the client using any
authentication credentials provided with the request. From Docker 1.11 the authentication credentials provided with the request. From Docker 1.11 the
Docker engine supports both Basic Authentication and [OAuth2](../oauth) for Docker engine supports both Basic Authentication and [OAuth2](oauth.md) for
getting tokens. Docker 1.10 and before, the registry client in the Docker Engine getting tokens. Docker 1.10 and before, the registry client in the Docker Engine
only supports Basic Authentication. If an attempt to authenticate to the token only supports Basic Authentication. If an attempt to authenticate to the token
server fails, the token server should return a `401 Unauthorized` response server fails, the token server should return a `401 Unauthorized` response

6
docs/content/spec/manifest-v2-2.md
View file

@ -71,7 +71,7 @@ image manifest based on the Content-Type returned in the HTTP response.
- **`digest`** *string* - **`digest`** *string*
The digest of the content, as defined by the The digest of the content, as defined by the
[Registry V2 HTTP API Specificiation](../api#digest-parameter). [Registry V2 HTTP API Specification](api.md#digest-parameter).
- **`platform`** *object* - **`platform`** *object*
@ -187,7 +187,7 @@ image. It's the direct replacement for the schema-1 manifest.
- **`digest`** *string* - **`digest`** *string*
The digest of the content, as defined by the The digest of the content, as defined by the
[Registry V2 HTTP API Specificiation](../api#digest-parameter). [Registry V2 HTTP API Specification](api.md#digest-parameter).
- **`layers`** *array* - **`layers`** *array*
@ -213,7 +213,7 @@ image. It's the direct replacement for the schema-1 manifest.
- **`digest`** *string* - **`digest`** *string*
The digest of the content, as defined by the The digest of the content, as defined by the
[Registry V2 HTTP API Specificiation](../api#digest-parameter). [Registry V2 HTTP API Specification](api.md#digest-parameter).
- **`urls`** *array* - **`urls`** *array*

2
docs/content/storage-drivers/inmemory.md
View file

@ -7,7 +7,7 @@ title: In-memory storage driver (testing only)
For purely tests purposes, you can use the `inmemory` storage driver. This For purely tests purposes, you can use the `inmemory` storage driver. This
driver is an implementation of the `storagedriver.StorageDriver` interface which driver is an implementation of the `storagedriver.StorageDriver` interface which
uses local memory for object storage. If you would like to run a registry from uses local memory for object storage. If you would like to run a registry from
volatile memory, use the [`filesystem` driver](../filesystem) on a ramdisk. volatile memory, use the [`filesystem` driver](filesystem.md) on a ramdisk.
{{< hint type=important >}} {{< hint type=important >}}
This storage driver *does not* persist data across runs. This is why it is only suitable for testing. *Never* use this driver in production. This storage driver *does not* persist data across runs. This is why it is only suitable for testing. *Never* use this driver in production.

3
docs/hugo.yaml
View file

@ -1,4 +1,4 @@
baseURL: / baseURL: https://distribution.github.io/distribution
languageCode: en-us languageCode: en-us
title: CNCF Distribution title: CNCF Distribution
theme: hugo-geekdoc theme: hugo-geekdoc
@ -22,3 +22,4 @@ disablePathToLower: true
params: params:
geekdocRepo: "https://github.com/distribution/distribution" geekdocRepo: "https://github.com/distribution/distribution"
geekdocEditPath: edit/main/docs geekdocEditPath: edit/main/docs
geekdocOverwriteHTMLBase: true

5
docs/layouts/_default/_markup/render-link.html Normal file
View file

@ -0,0 +1,5 @@
{{- if (strings.HasPrefix .Destination "http") -}}
<a href="{{ safe.URL .Destination }}" target="_blank">{{ safe.HTML .Text }}</a>
{{- else -}}
<a href="{{ ref .Page .Destination | safe.URL }}">{{ safe.HTML .Text }}</a>
{{- end -}}