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.
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, tune download concurrency and pull every release image. Air-gap flavour: load the images 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 three failures worth walking through step by step:
install-provisioning-stops-at-images is not in this bundle. Run npm run docs:sync to pull the current corpus.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. - 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