Docker and Helm

An admin first makes a repository with the format Docker (see Run the server). The name of the repository is the first part of the image name:

repo.example.com/docker/team/app:1.0

Here repo.example.com is the server, docker is the repository, and team/app:1.0 is the image and its tag. Put your own values in the commands below. The Use this repository tab of the repository shows the same commands with your values.

Pull an image

docker pull repo.example.com/docker/team/app:1.0

podman pull repo.example.com/docker/team/app:1.0

helm pull oci://repo.example.com/docker/mychart --version 0.1.0

Anyone can pull from a public repository. For a private repository, make a read token and log in once:

Open Settings › Tokens, and click New read token.

printf 'Read token: '; read -rs READ_TOKEN; echo
printf '%s' "$READ_TOKEN" | docker login repo.example.com -u YOUR_USERNAME --password-stdin

Helm and ORAS read the same login. With Podman, run podman login in place of docker login.

A repository can also be a proxy of Docker Hub, GitHub Container Registry or Quay. Pull from it in the same way. The server keeps a copy of each image that people pull.

Push an image from your computer

You do this once for each computer. The Telesphorepo CLI has a credential helper for Docker.

Open the Docker repository in the web UI, then the Publish to this repository tab.
Click Set up a project, and confirm with your second factor.
Copy the line for your system. Paste it in a terminal, then press Enter.
Terminal window
```
curl -fsSL https://repo.example.com/install.sh | sh -s -- setup 'https://repo.example.com/#/setup/trsu_...'
```
The line installs the CLI and approves this computer. It works once, for 10 minutes.
The CLI asks Add the credential helper to ~/.docker/config.json? [y/N]. Type y.

The CLI adds one entry under credHelpers for the server, and keeps every other entry.

Push.

docker tag app repo.example.com/docker/team/app:1.0
docker push repo.example.com/docker/team/app:1.0

Done when docker push prints the digest of the image.

Behind Cloudflare (Free and Pro plans), each image layer must be under 100 MB. Pulls have no limit. For larger layers, see Push large images.

After step 4, you do not run docker login. Docker, buildx, Podman, Helm and ORAS ask the helper for a token. Each push gets its own token for one repository, and the token ends within 15 minutes. An approval lasts 90 days, unless someone removes the device.

To push a Helm chart:

helm push mychart-0.1.0.tgz oci://repo.example.com/docker

A chart folder can also publish with the CLI. Run the setup line in the folder that holds Chart.yaml. The CLI writes telesphorepo.toml. Then telesphorepo publish packages the chart and pushes it.

Add the helper by hand

Install the CLI, and approve the computer:

curl -fsSL https://repo.example.com/install.sh | sh
telesphorepo login https://repo.example.com

Add this entry to ~/.docker/config.json:

{
  "credHelpers": {
    "repo.example.com": "telesphorepo"
  }
}

telesphorepo logout removes the entry and the approval of the computer.

Push with a publish token, with no helper

Open Settings › Tokens, and click New publish token. Choose the repository, then confirm with your second factor.

printf 'Publish token: '; read -rs TOKEN; echo
printf '%s' "$TOKEN" | docker login repo.example.com -u publish --password-stdin
docker push repo.example.com/docker/team/app:1.0
docker logout repo.example.com

A publish token works for the time of its session, 15 minutes by default. The push must end within that time. A password or a read token cannot push.

Push an image from CI

The credential helper of the CLI trades the identity token of the CI job for a publish token at each push. The job runs no docker login. An admin adds a CI pipeline for the job first, as in Run the server. The job needs Docker. The Publish to this repository tab shows the same files with your values.

GitHub Actions
Jenkins

on:
  push:
    branches: ["main"]

permissions:
  id-token: write
  contents: read

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - run: docker build -t "repo.example.com/docker/app:$GITHUB_SHA" .
      - run: curl -fsSL https://repo.example.com/install.sh | sh
      - name: Publish to docker
        run: |
          export DOCKER_CONFIG="$(mktemp -d)"
          printf '%s\n' '{"credHelpers":{"repo.example.com":"telesphorepo"}}' > "$DOCKER_CONFIG/config.json"
          docker push "repo.example.com/docker/app:$GITHUB_SHA"
        env:
          TELESPHOREPO_SERVER: "https://repo.example.com"

pipeline {
  agent any
  stages {
    stage('Build') {
      steps {
        sh 'docker build -t "repo.example.com/docker/app:${GIT_COMMIT:-$BUILD_NUMBER}" .'
      }
    }
    stage('Publish to docker') {
      steps {
        withEnv(['TELESPHOREPO_SERVER=https://repo.example.com']) {
          // The token is good for 10 minutes, so only this stage gets it.
          withCredentials([string(credentialsId: 'telesphorepo-id-token', variable: 'OIDC_TOKEN')]) {
            sh '''
              curl -fsSL https://repo.example.com/install.sh | sh
              export PATH="$HOME/.local/bin:$PATH"
              export DOCKER_CONFIG="$(mktemp -d)"
              printf '%s\\n' '{"credHelpers":{"repo.example.com":"telesphorepo"}}' > "$DOCKER_CONFIG/config.json"
              docker push "repo.example.com/docker/app:${GIT_COMMIT:-$BUILD_NUMBER}"
            '''
          }
        }
      }
    }
  }
}

The Jenkins credential telesphorepo-id-token comes from the plugin OpenID Connect Provider, with the audience https://repo.example.com.

Change app to the name of your image. The identity token of CI pulls public images only. To build from a private image, log in with a read token before the build.

If something goes wrong

Find your problem, then do the fix

name unknown or 404 on a push or a pull. Name an image inside the repository: repo.example.com/docker/team/app, not repo.example.com/docker.

publishing needs a publish session. You logged in with a password or a read token. These cannot push. Use the credential helper, a publish token or CI.

denied or 403 on a push. You cannot publish to this repository yet. Ask your server admin for Publish.

The push stops with 413 or a timeout on a large layer. Behind Cloudflare (Free and Pro plans), each layer must be under 100 MB. Ask your admin to turn on direct uploads. You keep the same commands. See Run in production.

ORAS or Helm says the upload Location is on a different host. Your admin turned on direct uploads. Push with ORAS and Helm to the upload address, for example helm push mychart-0.1.0.tgz oci://upload.example.com/docker. The Use this repository tab shows the right address.

The push says the token ended. The push took longer than the publish session. Ask your admin to raise publish.session_ttl, up to one hour.

Docker cannot reach an http:// server. Add the host to insecure-registries in /etc/docker/daemon.json, or serve the server over HTTPS.

You lost a laptop. Open Settings › Devices and revoke that laptop. To remove the key from a computer that you still have, run telesphorepo logout.

credentials not found in native keychain on a push. The computer has no approval for this server, or the approval ended. Run telesphorepo login https://repo.example.com, then push again.

The CI push says that the helper has no credential. Check id-token: write in the workflow, or the OIDC_TOKEN binding in Jenkins. TELESPHOREPO_SERVER must be the address of your server.

The registry must be at the root of a host. Docker cannot use an address with a path, such as https://example.com/repo. Give the server its own host name.