Install from the ISO
Run the unattended installer on bare metal or a virtual machine you build yourself — the boot menu, the provisioning stages, DHCP-less networking, and what each stopping message means.
- Version: 0.4
- Role: admin_user
- Type: task
Install a CID222 appliance from the installer ISO — the right choice for bare metal, for a virtual machine you build yourself, and for a site whose link to you is slower than its link to the internet. The installer is unattended: it lays down the operating system, then provisions the appliance and stops on a console status screen showing its address.
What do I need?
- Licence
- Any
- Role
admin_user
Prerequisites
- You have the installer ISO and the .sha256 file supplied with it, and you know whether it is the online or the air-gap flavour.
- The target machine has at least 32 GB of RAM, 8 CPU cores and a disk of at least 100 GB, and you accept that its largest disk will be erased.
- On the online flavour, the machine can resolve names and reach the CID222 registry on TCP 443 for the duration of the install.
- You know whether the network segment serves DHCP. If it does not, you need the manual-network boot entry.
- You have the console administrator password from your CID222 contact, if you may need to set a static address after the install.
- You have read Requirements and sizing and Network prerequisites.
The online flavour downloads roughly 10 to 15 GB of signed release images from the CID222 registry during provisioning, and needs nothing else from the network; the air-gap flavour carries those images on the media and downloads nothing. Both produce the same appliance, and both run without internet afterwards — updates are manual and operator-triggered.
Decide these before you boot the installer
Each row below is a decision the installer makes for you if you do not make it first, and each one is cheaper to settle now than to discover at the console an hour in.
| Decision | The answer that costs you nothing | The answer that needs an action first |
|---|---|---|
| Which flavour | Online, where the machine has HTTPS to the registry for the duration | Air-gap, where it does not. Ask your CID222 contact for air-gap media; you cannot convert one into the other |
| DHCP on the segment | Yes — use the standard boot entry | No — use Install … (set the network by hand — no DHCP). There is no path to a static address after an unattended install except the console |
| Firmware | BIOS. The installer and the appliance image are built and verified for it | UEFI boots the installer, and the boot menu shows an extra firmware entry, but keep the machine on BIOS for the appliance itself |
| Disk | One disk of at least 100 GB, and you accept that the largest disk is erased | Two disks, where the largest is not the one you meant. Detach or shrink the other before you boot |
| Network interfaces | One | Two or more. The installer lays down a name-wildcard DHCP configuration, so every interface asks for an address and the console can end up showing more than one. Decide which address your clients will use, and disconnect the others until the install has finished |
| Outbound proxy | None, or direct HTTPS | A proxy in front. The unattended entries never ask for one, so provisioning stops and you set it from the console before rebooting |
| TLS-inspecting proxy | None | One in the path. Ask for media built with your site's certificate authority, or install that certificate on the machine and reboot before the pull |
| Registry credentials | Media issued for this deployment | Media more than a release or two old. Confirm with your CID222 contact before the appointment; a withdrawn account fails the install at stage 6/8 |
| Storage controller | Whatever the platform assigns | Nothing to do. The packaged disk is boot-tested on virtio, SATA AHCI, LSI SCSI and VMware pvscsi |
| Newer hardware | The standard entry | A recent network or storage controller the standard kernel cannot see — use Install … (newer-hardware kernel) |
On a virtual machine, take a snapshot after the installer finishes and before you open the setup wizard. That snapshot is the cheapest way back to a clean appliance if the wizard is answered wrongly, because the wizard cannot be re-run. On bare metal the equivalent is reinstalling.
Warning
The unattended entries erase the machine's largest disk without asking, and the standard entry asks nothing at all. Confirm which disk that is before you press Enter.
Install the appliance
Verify the media
Compare the ISO against the .sha256 file shipped with it.
The command prints OK. A mismatch means a corrupted download — fetch it again rather than
installing from it. Where your media also carries a one-click checker (DOGRULA-VERIFY.bat
on Windows, sh verify.sh on Linux or macOS), it performs the same comparison and answers in
one line.
Boot the machine from the ISO
Attach the ISO as virtual media or write it to a USB device, and boot the machine from it.
The CID222 boot menu appears. It has seven entries, plus a firmware entry when the machine was started in UEFI mode:
| Entry | What it does |
|---|---|
| Install … [ERASES THE LARGEST DISK] | The standard unattended install. Use this one. |
| Install … (verbose, for support) | The same install with full logs on screen. Identical result; pick it only when support asks. |
| Install … (set the network by hand — no DHCP) | The same install, but it stops once on the installer's network page so you can enter a static address. |
| Install … (newer-hardware kernel) | The same install on a newer kernel, for recent network and storage controllers the standard kernel cannot see. |
| Manual install (standard Ubuntu Server installer) | The stock installer, for prescribed partitioning such as RAID, LUKS or a SAN volume. Expert use. |
| Rescue: root shell in the live environment (no installer) | No installer. A support tool for reading logs or repairing a machine that will not boot. |
| Check this installation media for defects | Verifies the media before installing. |
/assets/screenshots/iso-boot-menu@0.4.pngChoose the entry that matches your network
Select Install … [ERASES THE LARGEST DISK].
The installer starts immediately and asks nothing. It takes the machine's largest disk, so confirm that is what you intend before you press Enter.
The installer proceeds without further questions.
Let the installer run
Leave the machine alone. Expect 30 to 60 minutes on the online flavour, depending on bandwidth.
The run has four visible phases — operating system install, reboot, appliance provisioning, reboot — and provisioning itself reports its progress on the console as numbered stages, 0/8 to 8/8:
| Stage | What happens |
|---|---|
| 0/8 | Report why the previous attempt stopped, check memory, disk and the clock, apply a site proxy the installer was given, and install any site certificate authorities carried on the media. |
| 1/8 | Install the container runtime from packages on the media. |
| 2/8 | Confirm the storage drivers are present in the boot image. |
| 3/8 | Lay down the appliance's configuration and trust anchors. |
| 4/8 | Install the console interface, without starting it. |
| 5/8 | Generate this machine's own secrets. |
| 6/8 | Online flavour: probe the registry, sign in, measure the link and tune download concurrency. If a verified entitlement snapshot already exists, pull only entitled and mandatory images; otherwise the first install uses the release set and the licence-first wizard narrows later service choices. Air-gap flavour: load the signed image set from the media. |
| 7/8 | Install and enable the appliance's system services. |
| 8/8 | Start the stack, verify the containers, install the HTTPS listener, and reboot. |
Along the way the installer repairs several things without asking. It routes the registry's domain to public resolvers when your resolver cannot answer for it, and keeps that change so the updater inherits it; where it then has to pin the registry's address in the hosts file, it removes that pin again if the pin does not help. It measures the real download path and narrows to a single stream on a slow link. It retries timeouts, resets and TLS failures with a widening pause, keeping everything already downloaded, so an interrupted run — a power cut included — resumes on the next boot rather than starting over. It carries a site proxy into the container runtime's own configuration, because that runtime reads neither the package manager's configuration nor the shell environment. And it nudges time synchronisation before contacting the registry, because a wrong clock makes a valid certificate look invalid.
Read the appliance's address
Wait for the console status screen.
The screen names the appliance's address and the state of its services. Every run is recorded
in /var/log/cid-firstboot.log.
/assets/screenshots/iso-console-status@0.4.pngOpen the dashboard
Browse to https://<appliance-ip>/ and accept the one-time certificate warning.
The appliance redirects to the first-boot setup wizard, because it has no administrator yet.
Warning
An ISO-installed appliance serves HTTPS only. Opening http://<appliance-ip>/ renders a blank
page rather than an error, because the dashboard tells the browser to upgrade every asset
request to HTTPS and there is no listener on port 80 to answer.
Verify
- The console status screen's Appliance services line reports every container running — the
two numbers in
N/N runningmatch — rather than a partial count. The expected total is the number of services this release's default profile starts, and the screen counts it for you. https://<appliance-ip>/loads and lands on the setup wizard rather than a login form.- From a machine on the same network,
curl -ksS -o /dev/null -w '%{http_code}\n' https://<appliance-ip>/returns200. - On the console,
/var/log/cid-firstboot.logends with the stamp-and-reboot line of stage 8/8 and no error.
If it fails
A fault the installer cannot repair stops the run with one line naming the cause, printed under a red failure marker. Read the line: each cause needs a different action, and retrying blindly wastes the download.
| The console says | What it means |
|---|---|
| no IPv4 network (no default route) | The machine never received an address. Connect it to a network with DHCP, or reinstall with the manual-network boot entry. |
| resolves but HTTPS will not connect | Outbound 443 to the registry is blocked, or a proxy or TLS-inspection device is intercepting it. Allow direct HTTPS to that host, then reboot. |
| the disk filled up | Give the machine a larger disk and reinstall. Retrying on the same disk cannot succeed. |
| the registry rejected this appliance's credentials | The media is stale or its account was withdrawn. Ask your CID222 contact for current install media. |
| no longer published in the registry | The media predates the current release. Ask for current media. |
| the certificate presented for this registry is not trusted | This network inspects HTTPS and presents its own certificate. Install the site's certificate authority on the machine and reboot; the next run trusts it before the pull. |
| the previous attempt was killed by the kernel | The machine ran out of memory. Raise it to at least 32 GB and boot again — images already downloaded are kept, so the retry is quick. The message still names the earlier 16 GB design value. |
The stage the run stopped at narrows it further. The console names the stage, and
/var/log/cid-firstboot.log ends at it:
| Stopped at | What to do |
|---|---|
| 0/8 | A resource or clock check refused. Raise memory to at least 32 GB, or free disk, then boot again — see The installer stops on memory or free disk. A clock warning does not stop the run |
| 1/8 or 2/8 | The container runtime or the storage drivers could not be laid down. This is media damage or an unsupported machine: run Check this installation media for defects, then ask for current media |
| 3/8, 4/8 or 5/8 | The payload could not be written or the secrets could not be generated. Almost always a full or failing disk. Give the machine a larger disk and reinstall |
| 6/8, online flavour | Networking, credentials or trust. Work through Provisioning stops at container images — everything already downloaded is kept, so the retry is quick |
| 6/8, air-gap flavour | The image set on the media could not be loaded. Verify the media checksum and ask for a replacement |
| 7/8 | The appliance's own services could not be installed. Capture the log and contact your CID222 contact |
| 8/8 | The stack started and something did not come up healthy. The screen names each container and prints the last three lines of its log; exit code 137 is an out-of-memory kill |
Provisioning is re-run on every boot until it succeeds, keeping everything it has already done, so a machine that stopped for a reason you have now fixed is rebooted rather than reinstalled.
The three failures worth walking through step by step:
Provisioning stops at "6/8 container images"
You might see: 6/8 container images · cannot log in to api.cid222.live — the indented line above is docker's own message · FAILED: cannot log in to · provisioning stopped at 6/8
Before you start
Checks
- 1
Verify the machine holds an IPv4 address and a default route
expected · An IPv4 address and a default route are present. A VM summary showing only an fe80:: address means the port group has no DHCP.
- 2
Resolve the registry host with the resolver this machine actually uses
expected · An answer with an address that matches the one your CID222 contact gave you. SERVFAIL, a timeout, or a different address is a failure.
- 3
Open a TCP connection to the registry on 443 from the appliance itself
expected · The command prints 443 open.
- 4
Verify the certificate the registry presents is the registry's own
expected · The issuer is a public certificate authority, not your organisation's inspection CA.
- 5
Log in to the registry with the credentials on the media
expected · Login Succeeded.
- 6
Measure what this link actually sustains to the registry
expected · The measured rate is roughly 2 MB/s or better.
- 7
Check whether the previous attempt was stopped by the kernel or by a full disk
expected · No line reports "KILLED BY THE KERNEL" and none reports the disk filling up.
Causes and fixes
| Reached when | Cause | Explanation, fix and verification |
|---|---|---|
| check 1 fails | no-ipv4 (critical) | Provisioning downloads about 10-15 GB from the registry, so a machine with no address and no default route stops at the first pull. On vSphere and ESXi the usual reason is a port group with no DHCP: the VM comes up with a link-local fe80:: address only, which looks like a working NIC in the summary pane. Fix: Move the NIC to a network that serves DHCP, or set a static address from the appliance console: press Alt+F1 for the console, then F2, and set the address, gateway and name servers. Reboot afterwards — provisioning resumes by itself and keeps everything already downloaded. On VMware Workstation and Fusion, setting the adapter to NAT gives DHCP and egress with no further configuration. Verify: expected · An IPv4 address and a default route are present, and the run continues past 6/8. |
| check 2 fails | dns-cannot-resolve-registry (critical) | The appliance resolves names with this network's resolver. When that resolver cannot answer for the registry, every pull fails before a packet reaches it. Browsers keep working because they resolve over DNS-over-HTTPS, which is why the network is reported as open in good faith. The installer tries to route that one domain to public resolvers and, failing that, pins the address the media was built with — so a failure here means all three paths are blocked. Fix: Point the appliance at a resolver that can answer for the registry, from the console (Alt+F2, then F2 for the network page). If you cannot change the resolver, bypass DNS for that one name by adding the address your CID222 contact gives you to /etc/hosts, then reboot. Provisioning resumes automatically. Verify: expected · The answer is the address your CID222 contact gave you. |
| check 3 fails | https-blocked (critical) | Name resolution works and TCP 443 does not. Image pulls are TCP on 443, so nothing gets out. A firewall that permits ICMP and blocks 443 is an ordinary configuration, and Ubuntu's own mirrors are served over port 80 — which is why ping and apt both succeed while the install fails. Fix: Allow direct outbound HTTPS from the appliance to the registry host for the install window, then reboot. On a proxy-only segment, set the proxy from the console and reboot: first boot copies it into Docker's own configuration, because Docker reads neither apt's configuration nor the shell environment. If neither is possible, ask your CID222 contact for the air-gap media, which carries the images and downloads nothing. Verify: expected · The connection succeeds. |
| check 5 fails | registry-refuses-credentials (critical) | The registry answered and rejected this appliance. The installer's own wording is "the registry rejected this appliance's credentials — this install media is stale or its account was revoked". The credentials are baked into the media, so they age with it. Fix: Ask your CID222 contact for current install media. Nothing on the appliance can renew the credentials, and retrying the same ISO cannot succeed. Verify: expected · The registry login succeeds and the pull continues. If that does not apply: Quote the version in the boot menu entry and the date the media was issued. |
| check 4 fails | tls-inspection (critical) | This network terminates HTTPS and presents its own certificate, which the appliance does not trust. The installer reports "the certificate presented for this registry is not trusted — this network inspects HTTPS". Docker refuses the connection before authenticating. Fix: Put your site's CA certificate in /usr/local/share/ca-certificates on the appliance (console: Alt+F2), run update-ca-certificates, then reboot — the next run installs and trusts it before the pull. Media built for your site can carry that certificate already; ask your CID222 contact. A wrong clock produces a certificate error that reads the same, so confirm time sync first. Verify: expected · Login Succeeded, with no certificate error. |
| check 6 fails | link-too-slow (warning) | The image set is roughly 10-15 GB and single layers exceed 2 GB. Below about 2 MB/s a large layer never completes before docker gives up, so the pull restarts or times out at 6/8 while small requests — the login and the manifests — keep succeeding. The installer already measures the link, drops to a single download stream and raises the retry count, so hand- editing the docker daemon configuration is rarely the missing piece. Fix: Measure the real throughput from the appliance before blaming it. If the site cannot sustain roughly 2 MB/s, ask your CID222 contact for the air-gap ISO: it carries the images and downloads nothing. Verify: expected · The measured rate is above roughly 2 MB/s, or the air-gap media is in use. |
| check 7 fails | killed-or-full (critical) | The previous attempt was stopped by the machine, not by the network. An out-of-memory kill is reported as "the previous attempt was KILLED BY THE KERNEL"; a full disk stops the pull with "the disk filled up". Neither can be retried away on the same hardware. Fix: Raise the memory to at least the supported minimum of 32 GB, or give the machine a larger disk, and boot again. Images already downloaded are kept, so the retry is quick. See Resource check fails during the install. Verify: expected · Step 6/8 completes and the run reaches "8/8 starting the stack". |
This network has no DHCP, and the appliance comes up with no address
You might see: no IPv4 network (no default route) · the VM summary shows only an fe80:: address · the appliance has no IP address after the install · this network has no DHCP
Before you start
Checks
- 1
Check which boot menu entry this appliance was installed from
expected · The install was started, or will be started, from the "set the network by hand — no DHCP" entry.
- 2
Check whether a static address was set from the appliance console instead
expected · An IPv4 address, gateway and name servers are set, and a default route exists.
- 3
Verify the name servers you configured actually answer
expected · Both queries answer. A configured resolver that times out is worse than none, because the failure looks like a network outage.
Causes and fixes
| Reached when | Cause | Explanation, fix and verification |
|---|---|---|
| check 1 fails | wrong-boot-entry (warning) | The default boot entry is fully unattended and expects DHCP; it never asks for an address. On a segment with no DHCP that entry produces a machine with no network and an install that stops at the first pull. The dedicated entry shows a network page before it touches the disk. Fix: Reinstall from the boot entry "set the network by hand — no DHCP". The installer shows its own network page: select the interface, choose Edit IPv4 → Manual, fill in the subnet, address, gateway and name servers, then select Done. Nothing else is asked, and the address you type is the address the finished appliance keeps. Verify: expected · The appliance holds the address you typed, and provisioning ran to completion. |
| check 2 fails | no-static-address (critical) | No address was configured by hand and none was offered by the network, so the appliance has only a link-local address. Every outbound step — the registry pull, name resolution, the update channel — fails identically, which makes the cause hard to read from the symptoms. Fix: Set the address from the appliance console rather than reinstalling: press Alt+F1 for the console, then F2, and set the address, gateway and name servers. The console uses a US keyboard layout and warns when Caps Lock is on. Reboot afterwards — provisioning resumes by itself and keeps everything already downloaded. Verify: expected · The address you set is present and a default route exists. |
| check 3 fails | resolver-unreachable (critical) | A static configuration includes the name servers, and a wrong entry there produces an appliance that has an address and still resolves nothing. The installer then reports that it cannot resolve the registry with this network's DNS, with public resolvers, or from a pinned address. Fix: Correct the name servers on the console network page and reboot. If the site's resolvers cannot answer for the registry at all, add the address your CID222 contact gives you to /etc/hosts as a temporary bypass for the install window. Verify: expected · The query answers with the expected address. |
The appliance cannot get out — one or more egress tests failed
You might see: egress tests failed · the appliance cannot reach the registry · ETIMEDOUT after 5000ms · proxy returned 407 Proxy Authentication Required
Before you start
Checks
- 1
Verify the appliance actually ran its outbound probes
diagnostics · appliance.egress
- 2
Read the name-resolution results for the hosts this appliance must reach
diagnostics · appliance.dns
- 3
Read whether an outbound proxy is configured on the appliance
diagnostics · appliance.proxy.configured = true
- 4
Read whether the release channel answered on the last attempt
diagnostics · appliance.update.channelReachable = true
- 5
Check whether a TLS-inspection device is presenting its own certificate to the appliance
expected · The issuer is a public certificate authority, not your organisation's inspection CA.
Causes and fixes
| Reached when | Cause | Explanation, fix and verification |
|---|---|---|
| check 1 fails | probes-disabled (info) | The outbound probes are switched off for this deployment, so the snapshot carries no evidence either way and no egress finding can fire. This is a deliberate setting for a box that must make no outbound request at all. Fix: Re-enable the diagnostics egress probes on the gateway container and collect the snapshot again, or run the three tests by hand from the appliance host. The probes are the only outbound requests the appliance makes on its own. Verify: diagnostics · appliance.egress |
| check 2 fails | dns-broken (critical) | The appliance resolves with this network's resolver. A resolver that cannot answer for the provider or channel hosts fails every outbound call identically, and a browser on a laptop keeps working because it resolves over DNS-over-HTTPS. Nothing downstream of resolution can be diagnosed until this is fixed. Fix: Set a resolver that answers for the hosts in the DNS section of the snapshot, then collect the snapshot again. See Network prerequisites. Verify: diagnostics · appliance.dns |
| check 3 fails | proxy-not-configured (critical) | This site requires an outbound proxy and the appliance has none, so every outbound connection is attempted directly and times out. A timeout reads as a dead network rather than as a missing setting, which is why the network is reported as open. Fix: Configure the outbound proxy on the appliance and restart the gateway container so it re-reads the setting. Docker itself reads neither the shell environment nor apt's configuration, so a proxy set for the shell alone does not reach image pulls. Verify: diagnostics · appliance.proxy.configured = true |
| check 4 fails | https-path-blocked (critical) | Names resolve and the HTTPS path does not complete. DNS, a TCP connection on 443, and an authenticated HTTPS request fail independently: a firewall that permits ICMP and blocks 443 is ordinary, and Ubuntu's mirrors are served over port 80, so ping and apt both succeed while this fails. The three tests are not interchangeable. Fix: Allow direct outbound HTTPS from the appliance to the hosts the snapshot names as failing, or route them through the site proxy and configure it on the appliance. Read each failing target's detail line in the snapshot before changing a rule — a 407 is a proxy credential problem, a timeout is a blocked path, and a TLS error is inspection. Verify: diagnostics · appliance.update.channelReachable = true |
| check 5 fails | tls-inspection-untrusted (critical) | A middlebox terminates TLS and presents a certificate the appliance does not trust, so the connection fails at the handshake. The detail line reports a TLS error rather than a timeout, which is the only way to tell this apart from a blocked port. Fix: Install your site's CA certificate on the appliance so it trusts the inspection device, or exempt the appliance's outbound destinations from inspection. Both are legitimate; pick the one your security team already operates. Verify: expected · The failing egress targets report ok, or the issuer is now trusted by the appliance. |
Other symptoms, and where they lead:
- The browser shows a blank white page → you opened the appliance over plain HTTP. Open
https://<appliance-ip>/. If HTTPS refuses the connection outright, the HTTPS listener did not install; the console says so at the end of the run, and the install finished but the dashboard does not load walks it through. - A provisioning step failed and you want the general procedure rather than the per-stage table above → A first-boot provisioning step fails on the console.
- The installer looks frozen for 15 minutes or more, with no disk or network activity → power-cycle the machine and boot the ISO again. The installer is safe to re-run from scratch. If it repeats, run Check this installation media for defects.
- Pulls start and then stall or time out → measure the real throughput before blaming the appliance. The installer already narrows to a single download stream below roughly 2 MB/s and raises its retry count. Below that sustained rate, ask for the air-gap media instead.
- Provisioning finished but the console reports that some containers are not running → the install succeeded and a service did not stay up. The screen names each one and prints the last three lines of its log. Exit code 137 is an out-of-memory kill: give the machine more memory and reboot.
- The console password is rejected repeatedly → the console uses a US keyboard layout, watch the Caps Lock hint on screen, and beware look-alike characters. There is no paste at the console.
Next steps
- First boot and the setup wizard — create the administrator and choose the deployment mode.
- Licensing and activation — swap the built-in trial for your package.
- Naming, DNS and TLS — give the appliance names and a certificate the browser extension and Claude Code will accept.
Last updated on