Skip to main content

Getting Your Image

Overview​

A build delivers your ControlR server in one of two formats, chosen per slot by the Delivery format field. A Docker image slot publishes an image to a private container registry that belongs to the ControlR service, not to you. A ZIP download slot stores a self-contained server archive instead and never touches a registry. This page covers both paths. For what happens when sponsorship lapses, see Sponsorship Changes And Lapse.

Which Path Applies To Your Slot​

Open the slot and look at its Delivery format. Then read the matching half of this page and skip the other.

  • Docker image: read Your Image Reference downward. The builds panel hands you a pull command.
  • ZIP download: read If Your Slot Uses ZIP Download. No image reference and no pull command ever appear, because nothing is pushed to a registry for such a build.

If you are not sure which format the slot uses, the panel tells you. A Docker slot's delivery card is headed Image delivery. A ZIP slot's is headed ZIP delivery.

If Your Slot Uses ZIP Download​

A ZIP build produces no image and no pull command. The builds panel hands you a file instead.

On a successful build the delivery card reads ZIP delivery. It names the version and the runtime, and shows a Download server button. Select it and your browser downloads a server archive. The download link is created fresh when you ask for it and is short-lived. The card states that each download link is valid for a few minutes. If a link you copied earlier stops working, come back and select Download server again.

Every successful ZIP build in Recent build history carries its own Download server button, so you can retrieve an earlier build, not just the latest. Failed and cancelled rows carry no button.

While a ZIP build is still running, the card says a downloadable server archive becomes available once the build succeeds. There is nothing to download until it does.

The archive is an ordinary ControlR server for the runtime you picked, with your branding baked in. Running it is covered in Connect To ControlR.

Your Image Reference​

Every image your slot produces gets the same reference:

{registry host}/{your-login}/controlr:{your-login}-slot{N}

The registry host is the private registry the portal operators run. {your-login} is your sponsor GitHub login normalized for registry naming: lowercased, and any run of characters outside a-z, 0-9, ., _, and - replaced with a hyphen. The tag carries your login and the slot number. It does not carry a version, so the same slot always publishes to the same tag.

Example shape: registry.example.com/acme-corp/controlr:acme-corp-slot1.

The Pull Command​

When the latest build for a slot has produced an image, the builds panel's Image delivery block shows the image reference and the pull command. The command is masked. Select the eye icon to reveal it, then select Copy pull command. One command logs you in and pulls:

docker login {registry host} -u {username} -p {password} && docker pull {image reference}

Two permissions and one state gate this block. You need the slot's Credentials permission, titled "View registry credentials" in the portal's own warning text. Without it the block explains that you lack permission and to ask an account owner for it. And the slot must have a latest build that produced an image. Otherwise the block says the pull command appears once a build has produced an image.

The success email you get after a build carries the image reference and a docker pull line, but no login credentials. The combined command above only exists in the portal, because only the portal can hand out the password.

Where The Credential Comes From​

The username and password are not your GitHub credentials and not a secret you set. The portal provisions them per sponsor account in the registry:

  • The username is a registry token named like sponsor-{your-login}-token. Logins too long for Azure naming rules are shortened with a hash suffix.
  • The token is scoped read-only, and scoped to your own repository only. It can pull {your-login}/controlr and nothing else. It cannot push, and it cannot touch other sponsors' repositories.
  • The password is generated by the registry at the portal's request and stored encrypted by the portal for your account.

Credential Rotation, And When A Copied Command Dies​

The credential you copy is a snapshot. The portal treats the stored password as valid for 60 minutes. After that, the next time the portal provisions your credential, which happens automatically when a new build of yours succeeds, it asks Azure to generate a fresh password for the token. Azure replaces the old password rather than adding a second one, so every previously copied password stops authenticating.

Practical consequences:

  • A pull command you saved weeks ago will probably stop working. Come back to the portal, reveal the command on the slot, and copy a fresh one. The username does not change, the password does.
  • If a saved command suddenly fails with an authentication error right after a teammate triggered a new build, that is expected rotation, not a lockout. Copy the current command.
  • The password appears only when revealed in the portal and never in build history rows. Treat a revealed command like a password.

Updating A Running Server​

Because each slot owns one tag, a new successful build replaces what the tag points at in the registry. To move your server onto the new build:

  1. Re-run the login-and-pull command to fetch the new image layers onto the host.
  2. Recreate the container from the same tag. The container you are running keeps the old image until you recreate it.

To know which build you are on, check the slot's Built version line on its dashboard card against the image you are inspecting, or better, verify the image directly.

Confirming You Are Running What You Think​

The build stamps identity labels into every image it publishes. Inspect a pulled image to read them:

docker image inspect {image reference} --format '{{json .Config.Labels}}'

Expect three labels set by your build: org.opencontainers.image.version (the version built), controlr.sponsor (your normalized login), and controlr.slot (the slot number). If the version label does not match what the portal says was built last, you are looking at a stale local copy. Pull again.

Inside the running image, /app/wwwroot/downloads/Version.txt carries the same version, and the web UI shows your brand and colors rather than ControlR's defaults, which is the fastest visual check that you are running your build.

Registry Housekeeping You Should Know About​

Each slot keeps exactly one tagged image, the latest successful build. When a new build succeeds, the superseded image loses its tag, and the portal's cleanup sweep deletes untagged images once they are older than 7 days. The sweep runs at least daily. The practical meaning: the portal is not an image archive. Your build history rows keep pointing at references that no longer resolve once their image is reaped or once the slot's tag moved and aged out.

If keeping a specific build matters, pull it and push it to a registry you control under your own tag before it ages out. On lapse, the portal deletes your entire repository outright, tags and all.

What Comes After Pulling​

The image is an ordinary ControlR server. Deploying it alongside Postgres, setting the server's public URL and keys, and connecting agents is the same as any ControlR deployment. Start at Connect To ControlR and then the Installation and Docker Setup guides.