# Install the CloudRepo Edge on a Linux VM

> Install the CloudRepo Edge on a Linux VM, point your builds at it, and upgrade or remove it.

The CloudRepo Edge runs on your own network, next to your builds. Your builds pull through it, and it keeps copies of the files they pull on its own disk, each checked against CloudRepo’s SHA-256. It serves a kept file when CloudRepo has just approved that pull, for that SHA-256, with the build’s own credential.

This page installs one Edge on one Linux VM: one container, run by one systemd unit, with its store on the VM’s own disk. For an S3 bucket instead, see Keep the store in an S3 bucket, below.

## What you need

- A Linux VM (x86-64) with systemd and Docker Engine 29.7.2 or later, the version we test the Edge on. One Edge runs on each VM.
- At least 6 GiB of memory on that VM: 4 GiB for the Edge (the unit’s `--memory=4g`, step 6) and 2 GiB for the VM’s own system and Docker.
- A disk for the store, mounted at `/var/lib/cloudrepo-edge/store` by `/etc/fstab`, so it mounts at every boot. The Edge starts only once it is mounted. Size it for the files your builds pull. The Edge keeps the ones used most recently and removes the oldest when the disk fills. With an S3 bucket, skip this one: see below.
- The TLS certificate and key, as PEM files, for your `EDGE_HOST`, the name your builds use for CloudRepo (step 3).
- `cosign` 3.1.4 or later, the version CloudRepo signs and checks each release with, to check the image is CloudRepo’s before you run it. Get it from [cosign’s releases](https://github.com/sigstore/cosign/releases) and put it where root finds it: `sudo -H cosign version` prints its version.
- `curl` and `openssl`, to fetch CloudRepo’s signing key and check it is CloudRepo’s: `openssl version` prints its version.
- A join token for this Edge. The owner or an Admin of your organization mints it in CloudRepo, after a fresh check. Someone who signed in with a password uses their own second factor, and a password alone is not enough. Someone who signed in through your organization’s SSO signs in again at your identity provider. It is shown once and works for one hour.

## Current release

The Edge release this page installs. CloudRepo updates this section with each release. The image line names CloudRepo’s release host and ends in `@sha256:` and 64 characters, so it names exactly one image. Until the first Edge release ships, the block below says there is no Edge release yet: there is no image to install, and step 2 stops on that line.

```text
<no Edge release yet>
```

CloudRepo signs every release with one key. The SHA-256 of that key, which step 2 checks, is `69d46c47febb3506f383d8fad71faefff5c8c9f9b8b2f02ef4341035826b4655`.

## 1. Make the Edge’s directories

The Edge runs as its image’s own user, uid 65532, never as root. Each directory it uses belongs to that user and is open to it alone. Run these from the directory that holds your `tls.crt` and `tls.key`:

**Terminal**

```bash
sudo install -d -o 65532 -g 65532 -m 0700 /var/lib/cloudrepo-edge/identity /var/lib/cloudrepo-edge/store /var/lib/cloudrepo-edge/spool
sudo install -d -m 0755 /etc/cloudrepo-edge
sudo install -d -o 65532 -g 65532 -m 0700 /etc/cloudrepo-edge/tls /etc/cloudrepo-edge/bucket
sudo install -o 65532 -g 65532 -m 0600 tls.crt /etc/cloudrepo-edge/tls/tls.crt
sudo install -o 65532 -g 65532 -m 0600 tls.key /etc/cloudrepo-edge/tls/tls.key
```

To renew the certificate, put the new `tls.crt` and `tls.key` in `/etc/cloudrepo-edge/tls` the same way: the Edge picks up a renewed pair within a minute, with no restart and no dropped build. If the new pair is broken, the old one keeps serving and the Edge logs one line to the journal. A check that lands between the renewal’s two `install` lines sees the new certificate beside the old key, so it may log that line once before the line that says the new pair was loaded. On Kubernetes, mount the TLS Secret as a directory, never with `subPath`: a `subPath` mount never sees a Secret update, so the Edge could not reload it.

## 2. Get the image, by its digest

This step needs the first Edge release: until Current release, above, names an image line, there is nothing to get. Copy the image line from Current release. Put it in the first line below, then run the block. The image is public, so there is nothing to sign in to: CloudRepo’s signature, not a sign-in, proves the image is CloudRepo’s. The block checks the image line, then fetches CloudRepo’s signing key from [www.cloudrepo.io](http://www.cloudrepo.io). It refuses the file unless it holds exactly one key and nothing else, writes a clean copy of that key, and checks that the copy is CloudRepo’s: its SHA-256 must be the one under Current release, above. A key that is not CloudRepo’s stops the block, so a key swapped on the website never verifies an image. Then it verifies with that checked copy that CloudRepo signed the image and pulls it by its digest. Last, it reads the release version the image carries, which CloudRepo’s signature covers, and names the image for the Edge only if that version is 1.0.0 or newer, the oldest release this page installs. CloudRepo raises that number when a release has a known bug. So the block refuses an image line older than that, from a stale page or from anyone else:

**Terminal**

```bash
EDGE_IMAGE='<the image line from Current release>'
[[ $EDGE_IMAGE =~ ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.mycloudrepo\.io/repositories/[a-z0-9]([a-z0-9-]{0,30}[a-z0-9])?/cloudrepo-edge@sha256:[0-9a-f]{64}$ ]] || { echo "STOP: this is not CloudRepo's release image by digest"; false; } \
    && sudo curl -fsSL --proto '=https' --tlsv1.2 -o /etc/cloudrepo-edge/cosign.served.pub https://www.cloudrepo.io/docs/edge/cosign.pub \
    && { [[ $(sudo grep -c -e '-----BEGIN' /etc/cloudrepo-edge/cosign.served.pub) == 1 && $(sudo grep -c : /etc/cloudrepo-edge/cosign.served.pub) == 0 ]] || { echo "STOP: the key www.cloudrepo.io served is not one PEM block with no headers"; false; }; } \
    && sudo openssl pkey -pubin -in /etc/cloudrepo-edge/cosign.served.pub -out /etc/cloudrepo-edge/cosign.pub \
    && { [[ $(sudo openssl pkey -pubin -in /etc/cloudrepo-edge/cosign.pub -outform DER | sha256sum) == '69d46c47febb3506f383d8fad71faefff5c8c9f9b8b2f02ef4341035826b4655  -' ]] || { echo "STOP: /etc/cloudrepo-edge/cosign.pub is not CloudRepo's signing key"; false; }; } \
    && sudo -H cosign verify --key /etc/cloudrepo-edge/cosign.pub --insecure-ignore-tlog=true "$EDGE_IMAGE" \
    && sudo -H docker pull "$EDGE_IMAGE" \
    && EDGE_NEW=$(sudo -H docker image inspect --format '{{index .Config.Labels "org.opencontainers.image.version"}}' "$EDGE_IMAGE") \
    && { [[ $EDGE_NEW =~ ^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$ ]] && printf '%s\n' 1.0.0 "$EDGE_NEW" | sort -V -C || { echo "STOP: this image is Edge ${EDGE_NEW:-with no version}, older than 1.0.0, the oldest release this page installs"; false; }; } \
    && printf 'EDGE_IMAGE=%s\n' "$EDGE_IMAGE" | sudo tee /etc/cloudrepo-edge/image.env
```

Each step runs only once the one before it passed, so the block stops at the first check that fails and says why: nothing after it runs, and `image.env` is left as it was, even if you press Ctrl-C or your SSH session drops part way through. If it says STOP or a step fails, do not go on. If it says the key is not one PEM block or not CloudRepo’s signing key, tell CloudRepo. If it says the image is older than the oldest release this page installs, copy a newer image line from Current release and run the block again; remove the older image it pulled with `sudo docker image rm`.

Never copy the Edge’s image into a repository of your own, and never pull it through a proxy repository or through an Edge. An Edge that needs an Edge to start cannot start. The unit runs the image with `--pull=never`, so a start, a restart or a reboot pulls nothing from anywhere.

## 3. Write the Edge’s settings

Change the first two lines. `EDGE_HOST` is the name your builds use for CloudRepo, and your TLS certificate is for that name. It must be your organization’s CloudRepo host, like `your-org.mycloudrepo.io`, or a custom domain that CloudRepo support has set up for your organization: the Edge sends `EDGE_HOST` to CloudRepo with every request, and CloudRepo answers only a name that belongs to your organization. With your CloudRepo host, your builds keep the URLs they use today. You can’t get a public certificate for your CloudRepo host, a name CloudRepo owns, so make its certificate with your own CA and have your own DNS answer that name with the Edge for your build machines (split DNS); [Point your builds at the Edge](/docs/manage/edges.html#point-your-builds-at-the-edge), below, shows how your builds trust that CA. Its examples use `repo.example.com`, a custom domain, in place of your CloudRepo host. `EDGE_INGRESS` is where the Edge connects to CloudRepo: CloudRepo prints your organization’s `EDGE_INGRESS` line under your join token when it makes one, so copy that line. It is your organization’s CloudRepo host, then `:443`. That host is also in your repositories’ URLs in CloudRepo, the part before `/repositories/`, like `your-org.mycloudrepo.io`.

With your CloudRepo host as `EDGE_HOST`, both lines name the same host, so keep the Edge’s own VM out of the split DNS: the DNS server the Edge’s VM uses must give CloudRepo’s public answer for that host, or the Edge connects to itself and every build fails. For example, point the VM at a DNS server that does not carry your split answer. Step 7 checks it.

**Terminal**

```bash
sudo tee /etc/cloudrepo-edge/edge.env >/dev/null <<'EOF'
EDGE_HOST=your-org.mycloudrepo.io
EDGE_INGRESS=your-org.mycloudrepo.io:443
EDGE_API_URL=https://api.cloudrepo.io
EDGE_STORE_DIR=/var/lib/cloudrepo-edge/store
EDGE_SPOOL_DIR=/var/lib/cloudrepo-edge/spool
EOF
```

One limit to know. While this Edge can’t reach CloudRepo, it keeps serving each credential the files that credential pulled through it in the last 15 minutes (its default outage window). So a credential you just revoked can still pull those files from this Edge until that window ends. To turn this off, add `EDGE_OUTAGE_WINDOW=0` to this file; the Edge reads it when it starts.

## 4. Register this Edge, once

Make the join token’s file in the Edge’s identity directory:

**Terminal**

```bash
sudo install -o 65532 -g 65532 -m 0600 /dev/null /var/lib/cloudrepo-edge/identity/join-token
```

Put the token in it. Run this command on its own, paste the token, press Enter, then Ctrl-D:

**Terminal**

```bash
sudo tee /var/lib/cloudrepo-edge/identity/join-token >/dev/null
```

Then run the image once to register. It runs the image `image.env` names, the one step 2 verified:

**Terminal**

```bash
. /etc/cloudrepo-edge/image.env && sudo docker run --rm --pull=never --read-only --cap-drop=ALL --security-opt=no-new-privileges \
    --env-file=/etc/cloudrepo-edge/edge.env \
    --mount=type=bind,source=/var/lib/cloudrepo-edge/identity,target=/var/run/cloudrepo-edge/identity \
    --mount=type=bind,source=/var/lib/cloudrepo-edge/store,target=/var/lib/cloudrepo-edge/store \
    "$EDGE_IMAGE" register
```

`register` makes this Edge’s key, registers it with CloudRepo, writes the Edge’s identity (`edge-id`, `org` and `key.pem`, each mode 0600) and deletes the join token’s file. Running it again changes nothing. It reads the store first, and changes nothing in a new, empty one. A store an earlier Edge used is that Edge’s: see Replace an Edge, below.

If it says the store is on the same disk as its identity directory, the store’s disk is not mounted: nothing was sent and the token is not spent. Mount the disk at `/var/lib/cloudrepo-edge/store`, run step 1’s first line again so the store on it is the Edge’s own, then run this step again. If you mean the store to be on the VM’s own disk, run it with `register --fresh-store` in place of `register`.

If it says “revoke this Edge and mint a new token”, the token was spent or expired before an identity was written here: revoke the Edge it registered, if there is one, mint a new token, and run this step again. If it names a setting the owner must turn on, the same token works once it is on.

## 5. Open the Edge’s ports

Your builds must reach the Edge at `https://EDGE_HOST` on port 443, with your build machines resolving `EDGE_HOST` to the Edge. The unit in step 6 publishes 443 for you. Some links CloudRepo sends back use `https://EDGE_HOST` with no port, so a build that connects by IP address, another name, or another port would be sent off the Edge. Put no port in `EDGE_HOST`: the Edge refuses to start, and says why, if it names any port other than 443.

The Edge listens on two ports. Admit each one only from the hosts that need it:

| Port | Admit it from                                                                                         |
| ---- | ----------------------------------------------------------------------------------------------------- |
| 443  | your build machines and runners: the Edge’s proxy port                                                |
| 8081 | your load balancer’s health checks, if one is in front of the Edge (`/readyz` and `/readyz/degraded`) |

Docker publishes these ports ahead of the host’s own INPUT rules, so ufw and firewalld rules do not see them. Put the rule in Docker’s `DOCKER-USER` chain, as [Docker’s iptables guide](https://docs.docker.com/engine/network/firewall-iptables/) shows under “Match the original IP and ports for requests”. By the time a connection reaches that chain, Docker has already sent it on to the Edge’s own port inside the container, 8443, so the rule matches the port your build dialed, 443, with `--ctorigdstport`. For example, this drops every connection that arrives on `eth0` for port 443 and does not come from `10.0.0.0/8`; put your VM’s network interface and your build network in their places. It names the interface, so the Edge’s own connections out to CloudRepo pass:

**Terminal**

```bash
sudo iptables -I DOCKER-USER -i eth0 -p tcp -m conntrack --ctorigdstport 443 --ctdir ORIGINAL ! -s 10.0.0.0/8 -j DROP
```

A rule added this way is gone after a reboot: save it the way your distribution saves iptables rules.

## 6. Start it

Save the unit below as `cloudrepo-edge.service`, in the directory you run these from:

`cloudrepo-edge.service`

```ini
# cloudrepo-edge.service: the CloudRepo Edge on a Linux VM, as one container.
#
# Install and upgrade it as the Edge install guide says. It runs the Edge image named by its digest in
# /etc/cloudrepo-edge/image.env and pulls nothing (--pull=never): a start, a restart or a reboot never waits on a
# registry, on CloudRepo or on an Edge. The Edge's own image never comes through an Edge.
#
# The container runs as the image's own user, uid 65532, so the unit passes no --user: the identity, store and spool
# directories belong to that user, mode 0700. Restart=always brings the Edge back if it crashes or is killed, and
# WantedBy=multi-user.target starts it after a reboot, with no one at the keyboard. The identity, the TLS certificate
# and key, and the bucket key's directory are mounted read-only. The store and the spool are the VM's own directories,
# so a restart or an upgrade keeps them. The bucket key's directory is mounted on every VM, so a store in an S3 bucket
# needs no change here; with a store on disk it stays empty and the Edge never reads it. Docker needs that directory to
# exist, so ExecStartPre makes it, owned by the Edge's user, mode 0700, when it is missing. When it is there, it sets
# the same owner and mode again and leaves the key files in it as they are. The unit publishes the proxy port (443)
# and the health port (8081, /readyz), nothing else. Its log is the journal (journalctl -u cloudrepo-edge); Docker's
# own copy is capped at 30 MB. RequiresMountsFor holds the start until the store's disk, and every directory the
# container mounts, is mounted, so a disk that mounts late or not at all never leaves the Edge writing a new store onto
# the bare mountpoint. The Edge holds credentials in memory as it serves, so the container runs with 4 GiB of memory,
# no swap (--memory-swap equals --memory) and no core file (--ulimit=core=0). The Edge itself stays far under that
# memory. --memory is the one number to size: give --memory-swap the same value.
[Unit]
Description=CloudRepo Edge
Requires=docker.service
After=docker.service network-online.target
Wants=network-online.target
RequiresMountsFor=/var/lib/cloudrepo-edge/identity /var/lib/cloudrepo-edge/store /var/lib/cloudrepo-edge/spool /etc/cloudrepo-edge


[Service]
EnvironmentFile=/etc/cloudrepo-edge/image.env
ExecStartPre=-/usr/bin/docker rm --force cloudrepo-edge
ExecStartPre=/usr/bin/install -d -o 65532 -g 65532 -m 0700 /etc/cloudrepo-edge/bucket
ExecStart=/usr/bin/docker run --rm --name=cloudrepo-edge --pull=never \
    --read-only --cap-drop=ALL --security-opt=no-new-privileges \
    --memory=4g --memory-swap=4g --ulimit=core=0 \
    --log-driver=json-file --log-opt=max-size=10m --log-opt=max-file=3 \
    --env-file=/etc/cloudrepo-edge/edge.env \
    --publish=443:8443 --publish=8081:8081 \
    --mount=type=bind,source=/var/lib/cloudrepo-edge/identity,target=/var/run/cloudrepo-edge/identity,readonly \
    --mount=type=bind,source=/etc/cloudrepo-edge/tls,target=/var/run/cloudrepo-edge/tls,readonly \
    --mount=type=bind,source=/var/lib/cloudrepo-edge/store,target=/var/lib/cloudrepo-edge/store \
    --mount=type=bind,source=/var/lib/cloudrepo-edge/spool,target=/var/lib/cloudrepo-edge/spool \
    --mount=type=bind,source=/etc/cloudrepo-edge/bucket,target=/var/run/cloudrepo-edge/bucket,readonly \
    ${EDGE_IMAGE}
ExecStop=/usr/bin/docker stop --time=25 cloudrepo-edge
Restart=always
RestartSec=5
TimeoutStopSec=40


[Install]
WantedBy=multi-user.target
```

The unit gives the Edge 4 GiB of memory and no swap. `--memory` is the one number to size: to change it, set `--memory-swap` to the same value, and keep the VM 2 GiB larger than it.

Then install it and start it. It starts again by itself after a crash or a reboot:

**Terminal**

```bash
sudo install -m 0644 cloudrepo-edge.service /etc/systemd/system/cloudrepo-edge.service
sudo systemctl daemon-reload
sudo systemctl enable --now cloudrepo-edge
```

## 7. Check it is healthy

**Terminal**

```bash
systemctl is-active cloudrepo-edge
curl -fsS http://127.0.0.1:8081/readyz
sudo journalctl -u cloudrepo-edge -n 50 --no-pager
```

The first prints `active` and the second `ok`. The log has a `"serving"` line, and a line with `"level":"ERROR"` says what is wrong in its own words.

If `EDGE_HOST` is your CloudRepo host, also run `nslookup your-org.mycloudrepo.io` on the VM, with your host in its place. It must answer with CloudRepo’s addresses, not the address your builds get for the Edge. If it answers with the Edge’s, fix the VM’s DNS as step 3 says. With an outbound proxy, run the same check on the proxy instead.

Then point a build at `https://EDGE_HOST` using the steps in “Point your builds at the Edge” below.

## Point your builds at the Edge

Your builds use the Edge the way they use CloudRepo: the same repository URLs and the same repository tokens, with your `EDGE_HOST` in place of your organization’s CloudRepo host. Sign in with a repository token: CloudRepo refuses a password sent through an Edge. The examples use `repo.example.com` for `EDGE_HOST` and `your-repo` for your repository.

### npm

`npm login --auth-type=web` opens the portal in your browser. On a build machine that reaches only the Edge, sign in with a repository token instead. Put the token in the `NPM_TOKEN` environment variable, and add this line to the project’s `.npmrc` exactly as written (npm reads the variable itself, so the token is never on a command line):

`.npmrc`

```ini
//repo.example.com/repositories/your-repo/:_authToken=${NPM_TOKEN}
```

### Maven

Send every download through the Edge with a mirror, and give Maven your token in the `<server>` with the mirror’s id. Put the token in the `CLOUDREPO_TOKEN` environment variable:

`~/.m2/settings.xml`

```xml
<settings>
  <servers>
    <server>
      <id>cloudrepo-edge</id>
      <username>you@example.com</username>
      <password>${env.CLOUDREPO_TOKEN}</password>
    </server>
  </servers>
  <mirrors>
    <mirror>
      <id>cloudrepo-edge</id>
      <mirrorOf>*</mirrorOf>
      <url>https://repo.example.com/repositories/your-repo</url>
    </mirror>
  </mirrors>
</settings>
```

`<mirrorOf>*</mirrorOf>` sends every request Maven makes to that one URL, Maven Central’s included. So the repository in that URL, `your-repo`, must be a [group](/docs/consume/maven.html#pull-through-a-group-nexus-maven-public-artifactory-virtual) with a [Proxy repository](/docs/consume/proxy-repositories.html) of Maven Central as a member. A group without that member cannot serve a dependency from Maven Central.

Put your email address in `<username>`. To deploy through the Edge, use the same host in your project’s `<distributionManagement>` URL, and a `<server>` with that repository’s id. Deploy to a Hosted repository: a group is read-only.

### Docker

Sign in to the Edge’s host, with your token on standard input, then pull by the full reference:

**Terminal**

```bash
echo "$CLOUDREPO_TOKEN" | docker login repo.example.com --username you@example.com --password-stdin
docker pull repo.example.com/repositories/your-repo/my-app:1.0.0
```

`docker login` takes the host and nothing more. The pull and push references add `/repositories/your-repo/`.

### If your own CA signed the Edge’s certificate

Each build machine must trust that CA (PEM, here `edge-ca.pem`). How far that trust reaches depends on the tool, as noted below.

For npm, set `NODE_EXTRA_CA_CERTS` to the file’s full path in the environment that runs npm:

**Terminal**

```bash
export NODE_EXTRA_CA_CERTS="$HOME/edge-ca.pem"
```

Node adds that CA to the ones it already trusts, so public registries keep working. Every program that Node runs with that variable set trusts what your CA signs, for any host, not only `EDGE_HOST`.

For Maven, add it to the Java that Maven runs on. `mvn -v` prints that Java’s directory after `runtime:`: set `JAVA_HOME` to it. `keytool` asks for that Java’s store password, which is `changeit` unless someone changed it:

**Terminal**

```bash
sudo "$JAVA_HOME/bin/keytool" -importcert -cacerts -alias cloudrepo-edge -file edge-ca.pem -noprompt
```

This adds your CA to that Java’s own list of trusted CAs. Every program on that Java trusts what your CA signs, for any host, not only `EDGE_HOST`.

It prints `Certificate was added to keystore`. If `keytool` says `-cacerts` is an illegal option, that Java is older: give `-keystore` and the path of the `cacerts` file under its directory in place of `-cacerts`.

For Docker, put it in Docker’s directory for that host, as [Docker’s certificate guide](https://docs.docker.com/engine/security/certificates/) shows:

**Terminal**

```bash
sudo install -d /etc/docker/certs.d/repo.example.com
sudo install -m 0644 edge-ca.pem /etc/docker/certs.d/repo.example.com/ca.crt
```

Docker trusts it for that host and no other.

## Seed the store from Nexus

When you move a repository off Nexus, the Edge can start with that repository’s files already on its disk, read from your Nexus over your own network. The seed keeps a file only when its SHA-256 is the one CloudRepo recorded when the migration tool moved it, and the Edge checks every file again each time it serves it.

You need the list the migration tool wrote with `--landed-list` (`cloudrepo-migrate` 0.11.0 or later), and a read-only Nexus user. The seed reads only the files on that list. It sends that user’s name and password to your Nexus and nowhere else, and it sends nothing to CloudRepo.

Run it before you start the Edge the first time (step 6), or stop the Edge first with `sudo systemctl stop cloudrepo-edge`. While the Edge is stopped, builds that use it cannot pull: with one Edge, seed at a quiet time; with two, seed one at a time.

First make the seed’s directory and put the list in it. Run these from the directory that holds the migration tool’s list (here `landed.jsonl`):

**Terminal**

```bash
sudo install -d -o 65532 -g 65532 -m 0700 /var/lib/cloudrepo-edge/seed
sudo install -o 65532 -g 65532 -m 0600 landed.jsonl /var/lib/cloudrepo-edge/seed/landed-list
sudo install -o 65532 -g 65532 -m 0600 /dev/null /var/lib/cloudrepo-edge/seed/nexus-credential
```

If your own CA signed your Nexus’s certificate, put that CA’s certificate there too (here `nexus-ca.pem`):

**Terminal**

```bash
sudo install -o 65532 -g 65532 -m 0600 nexus-ca.pem /var/lib/cloudrepo-edge/seed/nexus-ca.pem
```

Put the Nexus user’s name and password in the credentials file, as `username:password` on one line. Run this command on its own, paste them, press Enter, then Ctrl-D:

**Terminal**

```bash
sudo tee /var/lib/cloudrepo-edge/seed/nexus-credential >/dev/null
```

Then run the seed. Change `https://nexus.example.com` to your Nexus’s URL, the one you gave the migration tool as `--nexus-url`:

**Terminal**

```bash
. /etc/cloudrepo-edge/image.env && sudo docker run --rm --pull=never --read-only --cap-drop=ALL --security-opt=no-new-privileges \
    --env-file=/etc/cloudrepo-edge/edge.env --env=EDGE_SEED_NEXUS_URL=https://nexus.example.com \
    --mount=type=bind,source=/var/lib/cloudrepo-edge/identity,target=/var/run/cloudrepo-edge/identity,readonly \
    --mount=type=bind,source=/var/lib/cloudrepo-edge/store,target=/var/lib/cloudrepo-edge/store \
    --mount=type=bind,source=/var/lib/cloudrepo-edge/spool,target=/var/lib/cloudrepo-edge/spool \
    --mount=type=bind,source=/var/lib/cloudrepo-edge/seed,target=/var/run/cloudrepo-edge/seed \
    --mount=type=bind,source=/etc/cloudrepo-edge/bucket,target=/var/run/cloudrepo-edge/bucket,readonly \
    "$EDGE_IMAGE" seed
sudo rm -f /var/lib/cloudrepo-edge/seed/nexus-credential
```

The URL must start with `https://`, so the Nexus user’s password never crosses your network unencrypted. If your Nexus speaks only http inside your own network, run `seed --allow-insecure-http` in place of `seed`: the seed then sends the password unencrypted, and its log says so.

If it says the store is on the same disk as its identity directory, the store’s disk is not mounted, and nothing was read or written. Mount the disk at `/var/lib/cloudrepo-edge/store` and run the seed again. If you registered with `register --fresh-store`, run `seed --fresh-store` in place of `seed`.

The seed deletes the credentials file when it finishes, even if it fails. The `rm` after it covers a run that was killed before it could. Then start the Edge (step 6), or start it again with `sudo systemctl start cloudrepo-edge`.

The seed’s last line counts every line of the list:

| Count                                                     | What it means                                                                                                                                                |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `seeded`                                                  | Read from Nexus, checked against CloudRepo’s SHA-256, and kept.                                                                                              |
| `stored`                                                  | Already on the Edge’s disk. Nexus was not asked.                                                                                                             |
| `past_target`                                             | Not read. The disk reached the point where the Edge would start removing files (30% free), so the seed stopped there, in the list’s order.                   |
| `mismatch`                                                | Nexus’s bytes are not the ones CloudRepo holds, so nothing was kept.                                                                                         |
| `nexus_unauthorized`                                      | Nexus refused the user (401 or 403). Check that it can read the repository.                                                                                  |
| `nexus_not_found`                                         | Nexus no longer has the file.                                                                                                                                |
| `nexus_other`                                             | Nexus answered something else, a redirect included. The seed never follows one.                                                                              |
| `nexus_unreachable`                                       | Nexus could not be reached, or sent nothing for a minute.                                                                                                    |
| `not_kept`                                                | The disk did not keep a checked file: it is full or failing.                                                                                                 |
| `too_large`                                               | Larger than the Edge’s spool holds (3.6 GiB), so it was not kept.                                                                                            |
| `no_digest`, `no_source`, `out_of_shape`, `line_too_long` | The line names no file the seed can check: no SHA-256, a checksum file Nexus does not store, a line not in the migration tool’s shape, or a line over 4 KiB. |

The first line skipped for each reason is logged with its line number. If it exits 1, Nexus or the disk skipped files a second run may keep, or the run was stopped: fix what those lines say, write the credentials file again, and run the seed again. It skips every file already on the disk. If it exits 2, a setting or a file must change first, and its `"level":"ERROR"` line says which. Nothing was read from Nexus, with one exception: if that line says the credentials file could not be deleted, the seed may have read and kept files first. The lines above it say how far it got and whether to run it again. Delete the credentials file with the `rm` above.

## Upgrade

We support every Edge release at or above the minimum version your portal shows. An older one keeps serving, but we fix problems only on supported releases.

Upgrade one VM at a time. The block is step 2’s with a restart at the end: it checks the new release’s image line, fetches CloudRepo’s signing key and checks its clean copy as step 2 does, verifies with that copy, pulls, checks the new release is 1.0.0 or newer, points the unit at it and restarts, each step only once the one before it passed. Like step 2, it signs in to nothing. The identity and the store stay, so the files the Edge kept before the upgrade are still on its disk after it. If a new release misbehaves, run the same block with the image line of the release you ran before to go back to it. The block pulls that image again, so this works even after it was removed from the VM.

**Terminal**

```bash
EDGE_IMAGE='<the new image line from Current release>'
[[ $EDGE_IMAGE =~ ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.mycloudrepo\.io/repositories/[a-z0-9]([a-z0-9-]{0,30}[a-z0-9])?/cloudrepo-edge@sha256:[0-9a-f]{64}$ ]] || { echo "STOP: this is not CloudRepo's release image by digest"; false; } \
    && sudo curl -fsSL --proto '=https' --tlsv1.2 -o /etc/cloudrepo-edge/cosign.served.pub https://www.cloudrepo.io/docs/edge/cosign.pub \
    && { [[ $(sudo grep -c -e '-----BEGIN' /etc/cloudrepo-edge/cosign.served.pub) == 1 && $(sudo grep -c : /etc/cloudrepo-edge/cosign.served.pub) == 0 ]] || { echo "STOP: the key www.cloudrepo.io served is not one PEM block with no headers"; false; }; } \
    && sudo openssl pkey -pubin -in /etc/cloudrepo-edge/cosign.served.pub -out /etc/cloudrepo-edge/cosign.pub \
    && { [[ $(sudo openssl pkey -pubin -in /etc/cloudrepo-edge/cosign.pub -outform DER | sha256sum) == '69d46c47febb3506f383d8fad71faefff5c8c9f9b8b2f02ef4341035826b4655  -' ]] || { echo "STOP: /etc/cloudrepo-edge/cosign.pub is not CloudRepo's signing key"; false; }; } \
    && sudo -H cosign verify --key /etc/cloudrepo-edge/cosign.pub --insecure-ignore-tlog=true "$EDGE_IMAGE" \
    && sudo -H docker pull "$EDGE_IMAGE" \
    && EDGE_NEW=$(sudo -H docker image inspect --format '{{index .Config.Labels "org.opencontainers.image.version"}}' "$EDGE_IMAGE") \
    && { [[ $EDGE_NEW =~ ^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$ ]] && printf '%s\n' 1.0.0 "$EDGE_NEW" | sort -V -C || { echo "STOP: this image is Edge ${EDGE_NEW:-with no version}, older than 1.0.0, the oldest release this page installs"; false; }; } \
    && printf 'EDGE_IMAGE=%s\n' "$EDGE_IMAGE" | sudo tee /etc/cloudrepo-edge/image.env \
    && sudo systemctl restart cloudrepo-edge
```

If it says STOP or a step fails, nothing changed: the Edge still runs the image it ran before.

Once the new Edge is healthy (step 7), remove the old image with `sudo docker image rm` and its image line.

## Remove

Stop the Edge and remove its unit:

**Terminal**

```bash
sudo systemctl disable --now cloudrepo-edge
sudo rm /etc/systemd/system/cloudrepo-edge.service
sudo systemctl daemon-reload
```

Then revoke the Edge in CloudRepo: on the **Edges** page, open the Edge, and under **Revoke this Edge** click **Revoke**, then the **Revoke** button that names the Edge.

Then delete its identity, the TLS key and the bucket key, so none of them stays on the VM:

**Terminal**

```bash
sudo rm -r /var/lib/cloudrepo-edge/identity
sudo rm -f /etc/cloudrepo-edge/tls/tls.key /etc/cloudrepo-edge/bucket/access-key-id /etc/cloudrepo-edge/bucket/secret-access-key
```

Delete the store too if no Edge will use it again.

### If the VM may have been compromised

Whoever is root on the VM sees every credential your builds send through the Edge, in the clear, and can use each one from anywhere until it is revoked. Step 3’s one limit holds here too. While this Edge can’t reach CloudRepo, it keeps serving each credential the files that credential pulled through it in the last 15 minutes (its default outage window). So a credential you just revoked can still pull those files from this Edge until that window ends. Once CloudRepo answers again, it refuses that credential. Do these steps in this order:

1. Revoke the Edge in CloudRepo first. From its next request, CloudRepo refuses each request it signs that sends a credential to read or write a repository or to sign in to Docker. A download already under way can finish. A revoke does not stop an anonymous pull of a public repository, a build’s own `HEAD`, or a request whose URL is too long for a proof (over about 2,600 characters). CloudRepo does not check the Edge’s proof on those, and answers them as if the build had sent them straight to it. A `HEAD` or a long URL can carry the build’s credential, so go on to step 2.

2. Revoke every credential your builds sent through the Edge:

   - Each person’s tokens: under **Users**, open the person and click **Revoke all tokens**. It revokes the repository tokens in their list, Docker sign-ins included, and the trust bindings they created or that act as them, and signs them out. An `npm login` token is in that list too, with format **npm**. Check that each token then reads **Revoked**, and click **Revoke** on any that does not.
   - Organization tokens, the ones your CI uses: on **Repository Tokens**, under **Organization tokens**, click **Revoke** on each.
   - Trust bindings your CI publishes with: on the **Trusted publishing** page (`/admin/trust-bindings` in the portal, also linked from a repository’s settings), click **Revoke** on each binding whose CI used the Edge. A token CI got through a binding ends with it.
   - Upload tokens from cloudrepo-migrate: each lasts at most an hour. To stop one sooner, revoke its login under **Migration logins**, linked from the **Organization tokens** section.
   - Subscriber access keys your customers pull with: under **Distribution**, on **Access keys**, click **Revoke** on each.

   Who may revoke whose: an Admin revokes a member’s tokens, Revoke all tokens included, organization tokens and migration logins. Only the owner revokes another Admin’s tokens, and the owner revokes their own on **Repository Tokens**. **Trusted publishing** takes the owner, an Admin, or a person given **Manage trusted publishing**. **Access keys** take **Manage software distribution**.

3. If a build still sent a CloudRepo password through the Edge, CloudRepo refused it, but root on the VM saw it: that person changes their password.

4. Revoke the TLS certificate for your builds’ name (your `EDGE_HOST`) with the authority that issued it. Its key was on the VM. Give the next Edge a new key and certificate.

5. Then stop the Edge and remove its unit, as above. Delete its identity and wipe the store’s disk: never give that store to another Edge. Rebuild the VM from a clean image before an Edge runs on it again.

## Replace an Edge, keeping its store

When you replace an Edge and its VM is not compromised (the VM is retired, the Edge moves to a new VM, or you rotate its identity), the new Edge can take the old one’s store and the files it kept. Every file is checked against CloudRepo’s SHA-256 before it is served. If you are not sure the VM is safe, follow If the VM may have been compromised, above, instead.

1. Revoke the old Edge in CloudRepo.
2. Stop it and delete its identity, as in Remove above. Keep the store. On the same VM, keep the TLS files too, or run step 1’s two TLS lines again.
3. On a new VM, move the store’s disk to it, mount it at `/var/lib/cloudrepo-edge/store`, and follow steps 1 to 3 first: the directories and the TLS files, the image, and the settings. On the same VM, make the identity directory again (step 1’s first line makes it).
4. Mint a new join token and follow step 4. `register` reads the old Edge from the store and asks CloudRepo for its store. CloudRepo hands it over only when that Edge is revoked, belongs to your organization, and no other Edge has taken its store. `register` then marks the store for the new Edge.
5. Start it (step 6).

If `register` says the old Edge is still active, revoke it and run step 4 again with the same token. If it says another Edge already took the store, or that your organization does not have that Edge, give the new Edge an empty store and run step 4 again with the same token. If it says to run it again once the store answers, run it again: it finishes the hand-over and sends nothing to CloudRepo. If the VM may have been compromised, never pass its store on: delete it.

## Two Edges

Give each VM its own join token, identity and disk, and follow every step on each. Put both behind your load balancer, which builds reach at `https://EDGE_HOST` on port 443 (step 5). Admit both of each Edge’s ports from it, and upgrade the Edges one at a time.

Add the line `EDGE_READY_FOLLOWS_UPSTREAM=true` to each VM’s `/etc/cloudrepo-edge/edge.env` (step 3) before you start it. On its own, with a health check of `/readyz`, this setting takes both Edges out of the pool when CloudRepo is down, so builds reach neither. The second check below, `/readyz/degraded`, is what keeps a pair serving the files from its outage window (step 3 says what that window is). With the load balancer below, the pair looks after itself:

- When one Edge loses CloudRepo, it steps aside, and its partner takes every build.
- When CloudRepo itself is down, each Edge stays in the pool while it has files from its outage window to serve (unless you set the outage window to `0`, which turns outage serving off: then both leave the pool, and builds see your load balancer’s own error). Each Edge serves the files each credential pulled whole through that Edge within its outage window. Any other pull gets that Edge’s 503 with `Retry-After: 5`.

Each Edge serves only the pulls that went through it, and the load balancer below has no stickiness. So in an outage, a pull can land on the Edge that never served that file to that credential, and get its 503. To keep each build machine on one Edge, add `balance source` to both backends (a sticky balancer that hashes the source address). Otherwise, count on each Edge to cover only its own recent pulls.

Docker pulls need CloudRepo to sign them in, so a `docker pull` through an Edge fails during an outage, even for an image pulled a minute before: the Edge sends Docker’s sign-in (`/v2/` and `/v2/token`) straight to CloudRepo. Outage serving covers Maven, npm, PyPI and Go package files, and the packages of an apt or yum proxy.

Each Edge keeps its own approvals; in an outage, a credential you revoke stops working on both within your outage window.

Each Edge answers two health checks on port 8081. `GET /readyz` answers 503 when CloudRepo has not answered that Edge for about 10 seconds, or has refused it, and `ok` again as soon as CloudRepo answers. `GET /readyz/degraded` answers the same, except while the Edge is cut off from CloudRepo with files from its outage window still to serve: then it answers 200, with a `CloudRepo-Edge-Degraded` header that says when that window closes.

Give the load balancer two backends over the same two Edges: `strict` checks `/readyz`, `degraded` checks `/readyz/degraded`, and builds go to `strict` while it has an Edge. For HAProxy, with your VMs’ addresses in place of `10.0.0.11` and `10.0.0.12` (`mode tcp` passes TLS through to each Edge, which holds the certificate from step 1):

```text
defaults
    mode tcp
    timeout connect 5s
    timeout client 6h
    timeout server 6h
    timeout check 2s


frontend edge
    bind :443
    use_backend strict if { nbsrv(strict) gt 0 }
    default_backend degraded


backend strict
    option httpchk GET /readyz
    http-check expect status 200
    server e1 10.0.0.11:443 check port 8081 inter 2s fall 2 rise 2
    server e2 10.0.0.12:443 check port 8081 inter 2s fall 2 rise 2


backend degraded
    option httpchk GET /readyz/degraded
    http-check expect status 200
    server e1 10.0.0.11:443 check port 8081 inter 2s fall 2 rise 2
    server e2 10.0.0.12:443 check port 8081 inter 2s fall 2 rise 2
```

Keep `timeout client` and `timeout server` at 6h. The first time a build pulls a file, the Edge sends nothing until it has fetched the whole file from CloudRepo and checked it, which can take up to 6 hours for a large file on a slow link. Your load balancer must wait as long as the Edge does, or it drops that build’s pull.

Never point a load balancer at `/readyz/degraded` alone: a single cut-off Edge would then stay in its pool. With `/readyz` alone, both Edges leave the pool together when CloudRepo is down, or a WAN link both VMs share is cut, and builds see your load balancer’s own error. They see it with both backends too once both windows close, until CloudRepo answers again. An older Edge answers `/readyz/degraded` with a 404, so its `degraded` backend stays empty. When cut off, it leaves both backends, just like a pair did before.

With one Edge, leave the setting out: the Edge stays ready and answers each build itself.

## Behind an outbound proxy

If this VM reaches the internet only through your HTTP proxy, add two lines to `/etc/cloudrepo-edge/edge.env` (step 3) before you register and start the Edge:

**Terminal**

```bash
EDGE_EGRESS_PROXY=http://proxy.example.com:3128
EDGE_EGRESS_NO_PROXY=.example.com,10.0.0.0/8
```

- `EDGE_EGRESS_PROXY` is your proxy’s `http://host:port`. The Edge reaches CloudRepo, `EDGE_API_URL` and an https bucket or Nexus through it, one CONNECT tunnel per connection. It asks the proxy for `EDGE_INGRESS` by name, so the proxy looks it up: the DNS server your proxy uses must give CloudRepo’s public answer for that host, never the Edge’s (step 3).
- `EDGE_EGRESS_NO_PROXY` is optional: a comma-separated list of names (each also covers every name under it), IP addresses or CIDR ranges the Edge connects to directly. Put your own bucket or Nexus here if the VM reaches it without the proxy.
- The Edge reads only these two lines. It ignores `HTTPS_PROXY`, `HTTP_PROXY` and `NO_PROXY`, so a proxy set for other programs on this VM never changes where the Edge connects.
- The proxy sees only the name and port of each tunnel. Your builds’ credentials and the Edge’s signatures travel inside TLS, which the Edge checks against its own trusted certificates, so a proxy that inspects TLS with a certificate the Edge does not trust gets a failed connection and no request.
- An `http://` bucket or Nexus is always reached directly, never through the proxy, so nothing crosses it in the clear.
- A proxy that needs a login is not supported yet: the Edge will not start with a login in `EDGE_EGRESS_PROXY`. Tell us if yours needs one.

**A proxy that inspects TLS.** If your proxy signs the connections it opens with its own certificate authority, give the Edge that CA’s certificate (PEM, here `proxy-ca.pem`). It goes in the identity directory step 1 made, which every `docker run` on this page mounts:

**Terminal**

```bash
sudo install -o 65532 -g 65532 -m 0600 proxy-ca.pem /var/lib/cloudrepo-edge/identity/proxy-ca.pem
```

Then add this line to `/etc/cloudrepo-edge/edge.env`:

```text
EDGE_CA_FILE=/var/run/cloudrepo-edge/identity/proxy-ca.pem
```

The Edge adds these certificates to the system’s trusted ones for its connections to CloudRepo. It never replaces them, and never uses them for your bucket, which keeps `EDGE_BUCKET_CA_FILE` (below). If the file is not owned by the Edge’s user, mode 0600, and at most 64 KiB of PEM certificates, the Edge does not start, and its log line names `EDGE_CA_FILE`.

If your proxy refuses a tunnel, builds get `503` with `edge_upstream_unavailable`, and the Edge’s log line names the egress proxy as the reason. Docker pulls the Edge’s image itself (step 2), so give Docker its own proxy setting if it needs one.

## Keep the store in an S3 bucket

The Edge can keep its files in an S3 bucket of your own, in place of the VM’s disk. Pick one. The Edge will not start with both `EDGE_STORE_DIR` and `EDGE_BUCKET_URL` set, or with neither.

What the bucket needs:

- A bucket for this Edge alone. An Edge will not start on a bucket another Edge owns.
- A key for that bucket alone, that can read and write objects in it. The Edge sends only reads and writes to the bucket, so the key needs no delete.
- A read of an object that is not there must answer 404. The Edge’s first read, of its marker, is one. Amazon S3 answers 403 unless the key may also list the bucket, so give the key list as well as read and write.
- Support for writes with `If-None-Match: *`, which the Edge uses to claim the bucket. If the bucket refuses such a write, the Edge starts and serves every pull from CloudRepo, keeps nothing, and logs a warning.
- The bucket must refuse a second create of the same key (If-None-Match: \*) with a 412; Dell ECS documents this from 3.5.1.4. A bucket that accepts it stops the Edge. A bucket that refuses it any other way (a 409, a 403 or a 501) leaves the Edge serving every pull from CloudRepo, keeping nothing, with a warning that says so.
- Path-style addressing: the bucket’s URL is your provider’s endpoint, then the bucket’s name as the whole path, with nothing after it.

### Check your bucket first

`check-bucket.sh` tells you in about a minute whether the bucket has what the Edge needs. Run it from any Linux host with bash and curl 7.34.0 or later, which RHEL 8 and 9 and Ubuntu 22.04 and 24.04 all have (`curl --version` prints it). This block downloads it from [www.cloudrepo.io](http://www.cloudrepo.io) into the directory you are in, and keeps it only if its SHA-256 is the one in the block. If it says STOP, it has removed the file: run the block again, and if it still says STOP, tell CloudRepo.

**Terminal**

```bash
curl -fsSL --proto '=https' --tlsv1.2 -o check-bucket.sh https://www.cloudrepo.io/docs/edge/check-bucket.sh \
    && echo '16c7a58ea4dcb0e4075fb24333e2c8604e2b819f4d981c4cba9e31b347c7717f  check-bucket.sh' | sha256sum -c \
    || { rm -f check-bucket.sh; echo "STOP: could not get CloudRepo's check-bucket.sh"; false; }
```

It needs the key’s two files: make them as “The bucket’s key” below says, in `/etc/cloudrepo-edge/bucket` or any directory you pass with `--key-dir`. Change the URL and the region to your bucket’s:

**Terminal**

```bash
sudo EDGE_BUCKET_URL=https://s3.example.com/cloudrepo-edge EDGE_BUCKET_REGION=us-east-1 bash check-bucket.sh
```

Once step 3 is done, `sudo bash check-bucket.sh --env-file /etc/cloudrepo-edge/edge.env` reads the same settings the Edge does.

It writes a few small objects under `v1/check/`, which the Edge never reads, and never lists the bucket. It never prints the key. Its last line names what it wrote and the command that removes them, for a key that may delete. Its output is safe to send us whole; add `--redact-host` to hide your endpoint’s name. Add `--large` to also write and read back one 3.6 GiB object. If your own CA signed the bucket’s certificate, add `--ca-file` and that CA’s file. If (f) passes with it, give the Edge the same file, as **Your own certificate authority** below says.

Each line says PASS, FAIL and what the Edge needs, or NOT CHECKED and why. If a FAIL stays, tell CloudRepo:

| Check                                                                          | If the bucket fails it                                                                                                  |
| ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| (d) A write with `If-None-Match: *` creates once; a second one answers 412.    | Refused: the Edge keeps nothing. Ignored and overwritten: the Edge stops. Do not use it.                                |
| (a) Path-style URLs over HTTP/1.1.                                             | The Edge cannot use the bucket. Every pull comes from CloudRepo.                                                        |
| (b) Writes signed with SigV4 over the body’s SHA-256, and no read without one. | The Edge cannot write, and keeps nothing. A bucket that serves a file with no signature lets anyone read what it keeps. |
| (c) One write of up to 3.6 GiB, never in parts (only with `--large`).          | The Edge does not keep larger files. Their pulls come from CloudRepo.                                                   |
| (e) 404 for an object that is not there.                                       | `register` stops, and a running Edge keeps nothing. On Amazon S3, give the key list too.                                |
| (f) TLS 1.2 or later, with a certificate a public CA or your own CA signed.    | The Edge cannot reach the bucket over https. For your own CA, give the Edge its file as `EDGE_BUCKET_CA_FILE` (below).  |

Follow steps 1 to 7 with these changes.

**Step 3.** Take out the `EDGE_STORE_DIR` line and put these two in its place:

```text
EDGE_BUCKET_URL=https://s3.example.com/cloudrepo-edge
EDGE_BUCKET_REGION=us-east-1
```

The URL starts with `https://`, or `http://` for a bucket inside your own network, and has no login, query or fragment. The bucket’s name is 3 to 63 lowercase letters, digits, dots and dashes, and starts and ends with a letter or a digit. `EDGE_BUCKET_REGION` is the bucket’s region. It is `us-east-1` if you leave it out. Keep the `EDGE_SPOOL_DIR` line: the Edge uses its spool with a bucket too. With an `http://` URL the Edge logs a warning when it starts, since its files then cross your network unencrypted. It still checks every file against CloudRepo’s SHA-256 before it serves it.

Step 1 still makes `/var/lib/cloudrepo-edge/store`. The unit mounts it, and with a bucket the Edge leaves it empty, so it needs no disk of its own.

**The bucket’s key.** Step 1 created `/etc/cloudrepo-edge/bucket`. The unit and the seed mount it read-only where the Edge looks for it. After step 3, create the two key files in that directory. As in step 1, they must be owned by the Edge’s user and accessible only to that user:

**Terminal**

```bash
sudo install -o 65532 -g 65532 -m 0600 /dev/null /etc/cloudrepo-edge/bucket/access-key-id
sudo install -o 65532 -g 65532 -m 0600 /dev/null /etc/cloudrepo-edge/bucket/secret-access-key
```

Put your access key id in the first file. Run this command on its own, paste the id, press Enter, then Ctrl-D:

**Terminal**

```bash
sudo tee /etc/cloudrepo-edge/bucket/access-key-id >/dev/null
```

Put your secret access key in the second file the same way:

**Terminal**

```bash
sudo tee /etc/cloudrepo-edge/bucket/secret-access-key >/dev/null
```

Each file holds one value, with no space or line break inside it, and is at most 1,024 bytes. A newline at the end is fine. Each must be a plain file, or a link to one (a Kubernetes Secret lays its files out as links). A named pipe, a directory or a device is refused, and the Edge says which it found.

**Your own certificate authority.** Skip this if a public CA signed your bucket’s certificate. If your own CA signed it, as it often does for storage inside your network, put that CA’s certificate (PEM, here `bucket-ca.pem`) in the key’s directory, as the Edge’s user’s and open to it alone:

**Terminal**

```bash
sudo install -o 65532 -g 65532 -m 0600 bucket-ca.pem /etc/cloudrepo-edge/bucket/ca.pem
```

Then add this line to `/etc/cloudrepo-edge/edge.env`, beside the two from step 3:

```text
EDGE_BUCKET_CA_FILE=/var/run/cloudrepo-edge/bucket/ca.pem
```

The unit, the seed and the register command below see the key’s directory there, so the file needs no mount of its own. The Edge checks your bucket’s certificate against this CA alone and uses it for nothing else. CloudRepo’s certificate is still checked against the public CAs in the Edge’s image. The file must be a plain file (or a link to one), mode 0600, and at most 64 KiB of PEM certificates. The bucket’s URL must start with `https://`. If anything is wrong with it, the Edge, `register` and `seed` stop before they send anything, and the `"level":"ERROR"` line names `EDGE_BUCKET_CA_FILE` and what is wrong.

**Step 4.** Create the join token file and put the token in it, as written. Then register with this command instead of the last command in step 4. It mounts the key’s directory where the Edge looks for it, `/var/run/cloudrepo-edge/bucket`, and leaves out the store directory, which a bucket does not use:

**Terminal**

```bash
. /etc/cloudrepo-edge/image.env && sudo docker run --rm --pull=never --read-only --cap-drop=ALL --security-opt=no-new-privileges \
    --env-file=/etc/cloudrepo-edge/edge.env \
    --mount=type=bind,source=/var/lib/cloudrepo-edge/identity,target=/var/run/cloudrepo-edge/identity \
    --mount=type=bind,source=/etc/cloudrepo-edge/bucket,target=/var/run/cloudrepo-edge/bucket,readonly \
    "$EDGE_IMAGE" register
```

`register` reads the bucket’s marker before it sends anything. If a key file is missing or invalid, or the bucket cannot be read, it stops and says what is wrong, and the join token is not spent. The notes about an unmounted disk and `register --fresh-store` apply to a disk store only.

**Step 7.** These checks pass even when the bucket is out, because the Edge then serves every pull from CloudRepo and keeps nothing. So read the log too. A line with `"level":"WARN"` that names the bucket says what is wrong: the bucket cannot be reached, or it refuses the write above. A bucket that another Edge owns is different, and so is one that accepts a second create of the same key, or a key file that is missing or in the wrong form: the Edge stops, and its `"level":"ERROR"` line says so. If the bucket is out or slow when the Edge starts, it cannot check yet: the Edge starts, serves every pull from CloudRepo, and logs that `"level":"ERROR"` line when it finds out. It keeps nothing from then on and stops at its next start.

**To replace an Edge and keep its bucket,** give the new Edge the same bucket URL and key, and follow Replace an Edge, keeping its store, above, with the bucket in place of the disk.

**To remove an Edge,** revoke it in CloudRepo, then delete its bucket key at your provider. Delete the bucket’s objects too if no Edge will use them again.

**If the VM may have been compromised,** root on it could read the bucket key. Do the steps under Remove, and also revoke that key at your provider. Delete the bucket’s objects in place of wiping the disk, and never give that bucket to another Edge.

---

The page: https://www.cloudrepo.io/docs/manage/edges.html
