Kotar Enterprise Instructions - planetaryutilities/kotar-support GitHub Wiki

Kotar Enterprise – Docker Hub Access and Deployment

Overview

Planetary Utilities distributes Kotar Enterprise through a private Docker Hub repository.

Repository: https://hub.docker.com/r/planetaryutilities/kotar-enterprise

Your organization receives a Docker Hub Organization Access Token (OAT) granting read-only access to this repository.

The token allows your organization to download Kotar Enterprise Docker images without becoming a member of the Planetary Utilities Docker Hub organization.

1. Credentials

Planetary Utilities provides the following information:

Setting	Value
Registry	`docker.io`
Username	`planetaryutilities`
Password	Organization Access Token (OAT)
Repository	`planetaryutilities/kotar-enterprise`
Image version	`0.3.5` or the version provided
Permission	Image Pull (read-only)

Important: The OAT is a registry credential, not a password for an individual Docker Hub account.

Treat it as a secret. Do not commit it to Git, include it in Dockerfiles, or share it through unencrypted email.

2. Authenticate to Docker Hub

Standard Docker Login

Open a terminal or PowerShell and run:

docker login --username planetaryutilities

When prompted for a password, paste the OAT provided by Planetary Utilities.

Expected response:

Login Succeeded

Note: The OAT is used with the Docker CLI, not to sign in to the Docker Hub website or Docker Desktop graphical interface.

Using the OAT Alongside an Existing Docker Hub Account

If you are already authenticated with your own Docker Hub account, use an isolated Docker configuration directory to avoid replacing your existing credentials.

Linux / macOS

mkdir -p ~/.docker-kotar

docker --config ~/.docker-kotar login --username planetaryutilities

docker --config ~/.docker-kotar pull planetaryutilities/kotar-enterprise:0.3.5

Windows PowerShell

New-Item -ItemType Directory -Force "$HOME\.docker-kotar"

docker --config "$HOME\.docker-kotar" login --username planetaryutilities

docker --config "$HOME\.docker-kotar" pull planetaryutilities/kotar-enterprise:0.3.5

This keeps Kotar registry authentication separate from your existing Docker configuration.

3. Pull Kotar Enterprise

Once authenticated, pull the approved version:

docker pull planetaryutilities/kotar-enterprise:0.3.5

Expected result:

Status: Downloaded newer image for planetaryutilities/kotar-enterprise:0.3.5

If the image is already downloaded, Docker may report that it is up to date.

Verify the Download

docker image ls planetaryutilities/kotar-enterprise

The output should include:

REPOSITORY                          TAG
planetaryutilities/kotar-enterprise 0.3.5

The Docker image is now available locally.

4. Deploy with Docker Compose

Kotar Enterprise requires additional configuration for OIDC authentication and GitLab integration.

After preparing the required configuration, create a compose.yaml file:

services:
  kotar:
    image: planetaryutilities/kotar-enterprise:0.3.5
    env_file:
      - kotar.env
    secrets:
      - oidc_client_secret
      - session_secret
    ports:
      - "8080:8080"
    restart: unless-stopped

secrets:
  oidc_client_secret:
    file: ./secrets/oidc_client_secret
  session_secret:
    file: ./secrets/session_secret

The kotar.env file must contain the required OIDC and GitLab configuration.

Both referenced secret files must exist before starting the container.

Start:

docker compose up -d

Verify container status:

docker compose ps

Check application health:

curl -sS -o /dev/null -w '%{http_code}\n' http://localhost:8080/healthz

Expected HTTP status:

For production deployments, configure an HTTPS reverse proxy. The IDE requires HTTPS when accessed through a hostname other than localhost.

5. Kubernetes Deployment

For Kubernetes deployments, create an image pull secret containing the OAT.

5.1 Create the Registry Secret

Linux / macOS

read -rsp "Docker Hub OAT: " DOCKERHUB_OAT
echo

kubectl -n YOUR_NAMESPACE create secret docker-registry kotar-enterprise-pull \
  --docker-server=https://index.docker.io/v1/ \
  --docker-username=planetaryutilities \
  --docker-password="$DOCKERHUB_OAT"

unset DOCKERHUB_OAT

Replace YOUR_NAMESPACE with the target namespace.

The namespace must already exist.

For automated deployments, retrieve the token from your organization's secret-management system rather than embedding it in deployment scripts.

5.2 Reference the Registry Secret

Add imagePullSecrets to the Kubernetes Deployment:

spec:
  template:
    spec:
      imagePullSecrets:
        - name: kotar-enterprise-pull
      containers:
        - name: kotar
          image: planetaryutilities/kotar-enterprise:0.3.5

Kubernetes uses the supplied credentials to authenticate to Docker Hub and pull the private image.

The registry secret must exist in the same namespace as the application.

Note: This is a configuration fragment, not a complete Kubernetes Deployment manifest.

6. Updating Kotar Enterprise

When Planetary Utilities publishes a new release, update the image tag.

For example:

docker pull planetaryutilities/kotar-enterprise:NEW_VERSION

Update the image reference in compose.yaml:

image: planetaryutilities/kotar-enterprise:NEW_VERSION

Apply the update:

docker compose up -d

The existing OAT can be reused for newer versions as long as it remains valid and retains repository access.

For production deployments, use explicit version tags rather than latest.

7. Token Security

The OAT grants access to a private commercial software image and must be protected accordingly.

Store the OAT in your organization's approved secret-management system.
Restrict access to personnel and deployment automation requiring image-pull permissions.
Never commit the OAT to Git or include it in container images.
Do not share the token through unencrypted email or support tickets.
Contact Planetary Utilities if the token is compromised or expires.
Remove obsolete credentials when they are no longer required.

The OAT grants permission to download images. It does not grant access to Planetary Utilities systems, GitLab repositories, or other Docker Hub repositories.

Revoking the token prevents subsequent authenticated pulls but does not remove images already downloaded.

8. Troubleshooting

Problem	Possible cause / solution
`unauthorized: authentication required`	Incorrect, expired, or revoked OAT
`pull access denied`	Token lacks Image Pull permission or repository name is incorrect
`manifest unknown`	Requested image version is unavailable
Docker login succeeds but pull fails	Repository permission is missing
Kubernetes `ImagePullBackOff`	Missing or incorrectly configured image pull secret
Docker Desktop login fails	Authenticate through the Docker CLI using `docker login`
Application exits after start	Verify OIDC and GitLab configuration
Token expired	Request a replacement OAT from Planetary Utilities

For Docker Compose troubleshooting:

docker compose ps
docker compose logs kotar

For Kubernetes:

kubectl -n YOUR_NAMESPACE get pods
kubectl -n YOUR_NAMESPACE describe pod POD_NAME

Never include the OAT in support requests or diagnostic output.

9. Support and References

Publisher: Planetary Utilities
Product: Kotar Enterprise
Docker repository: https://hub.docker.com/r/planetaryutilities/kotar-enterprise

Additional references:

For deployment assistance, provide the Docker version, image tag, and relevant error messages, excluding all credentials.