Adding a server

Before you start

You need a clean Linux server that CICDoo can reach over SSH. The wizard's "Before you continue" box lists the requirements:

• Inbound TCP open on your SSH port (22 unless your provider uses another one), plus ports 80 and 443. Ports 80 and 443 serve your instances and are needed to issue SSL certificates.
• Those ports open in both places: your cloud provider's firewall or security group, and the operating system firewall (for example ufw). If a port is closed the server is still created, but the preparation job fails.
• A clean Ubuntu 22.04 or 24.04 host with at least 2 vCPU, 4 GB RAM and 40 GB disk. Existing web or database servers on the host can conflict with what CICDoo installs.
• Access as root, or as a user with passwordless sudo. CICDoo installs Docker, nginx and a monitoring agent.

The "Add Server" button only appears if you are allowed to add servers. Workspace members need the "Add servers" permission, see Member permissions and resource access.

Adding a server

The "Add New Server" window is a five-step wizard: Basics, Domain, Access, Maintenance and Review. Click Next to move forward and Back to return. You can also click a step name at the top, but the wizard stops at the first step that still has a missing or invalid field, and a short hint next to the buttons tells you what is missing.

1. Open the Servers page and click "Add Server".
2. On the Basics step, fill in:
   • Server Name: a label for your own lists and environment pickers, for example "Production EU". You can change it later.
   • SSH Username: the account CICDoo logs in as. Use root unless you have a sudo user configured for unattended commands.
3. Click Next. On the Domain step, choose how the server is addressed (see "Choosing a domain option" below), and open "Advanced network options" if the server sits behind a Cloudflare proxy or a load balancer.
4. Click Next. On the Access step, pick an Authentication Method and provide the matching credential (see "Choosing an authentication method" below).
5. Click Next. On the Maintenance step, check the log size and leave the two one-shot options off for a fresh machine (see "Maintenance options" below).
6. Click Next. On the Review step, check the Summary: name, SSH username, SSH port, hostname, instance addresses, authentication, network and log size.
7. Read "What happens next", then click "Add Server".

If something goes wrong when you submit, the error is shown in red on the Review step and the server is not created. Fix the field and click "Add Server" again.

Choosing a domain option

The Domain step has a "Use my own domain" toggle, which is off by default.

• Toggle off (a cicdoo.com address): enter the Server IP Address, the public IPv4 address of the server. CICDoo creates a cicdoo.com subdomain for the server and one managed DNS record per instance, so you do not need to touch DNS at all. Your instances are reachable on cicdoo.com addresses rather than your own brand.
• Toggle on (your own domain): enter the Server Hostname, a hostname you own such as srv1.example.com. Use a subdomain, not your bare root domain, and not an IP address. A preview shows the address an example instance would get.

If you use your own domain, set up DNS before you submit:

1. Add an A record for the hostname pointing to your server's IP. CICDoo resolves the hostname the moment you submit, and creation fails if it does not resolve yet.
2. Add a wildcard A record, for example on *.example.com, pointing to the same IP. Every instance replaces the first part of the hostname, so srv1.example.com publishes an instance at an address like main-shop.example.com.

Every project you assign to this server builds its instance addresses from this hostname, so pick the final one now. Changing it later changes the address of every instance on the server. More detail is in Server domains and DNS.

If you type an IP address into Server Hostname, the wizard shows a "Use a cicdoo.com address for this IP" button. Click it to switch the toggle off and move the IP into the Server IP Address field.

If SSH on your server does not listen on port 22, add the port after a colon, for example srv1.example.com:222 or 203.0.113.10:222.

Advanced network options

Open "Advanced network options" on the Domain step only if your setup needs it:

• Cloudflare Proxy: turn on only if the server's DNS records are proxied by Cloudflare (orange cloud). With proxying on, CICDoo skips SSL certificate generation and relies on Cloudflare for HTTPS.
• Connectivity IP: the real address of the machine. It is required if your domain is proxied, because the hostname then resolves to the proxy, which breaks SSH and stops CICDoo recognising the server when it calls back. You can list several addresses separated by commas if the server connects out through a different address than it listens on; the first one is used for SSH.
• Load Balancer: turn on if the server sits behind a load balancer, then enter the Load Balancer IP. See Using a load balancer.

Choosing an authentication method

The Authentication Method list on the Access step has three options. Whichever you choose, the credentials are stored encrypted and used only to run deployments on this server.

• Public Key (recommended): nothing to upload and no secret of yours to store. The "Public Key Authentication Setup" box shows CICDoo's public key.
• Private Key: upload a Private Key File whose public half is already in authorized_keys on the server. It must not be protected by a passphrase, because deployments run unattended.
• Password: enter the SSH password for the username from the Basics step. Password logins must be enabled in the server's SSH configuration (PasswordAuthentication yes).

Setting up public key access

Do this before you finish the wizard:

1. On the Access step, choose "Public Key (recommended)".
2. Click the copy button next to the key shown in the "Public Key Authentication Setup" box.
3. On your server, add the key as a new line in the ~/.ssh/authorized_keys file of the user you entered as SSH Username.
4. If you want to see how it is done, click "Watch tutorial: How to add public key" to open the "How to Add Public Key" video (shown only when a tutorial video is available).
5. Continue with Next.

Maintenance options

• Log Max Size (MB): per-instance log files (Odoo, sessions, backup, restore, PostgreSQL, nginx) are truncated when they exceed this size, keeping the most recent part. Set it to 0 to disable truncation.
• Force Nginx Reinstall (next deploy): wipes the nginx configuration and reinstalls it on the next deploy. Use it only to recover from a corrupt nginx configuration, because it interrupts traffic to all instances.
• Force Generate SSL (next deploy): re-issues the server's certificate on the next deploy even if a valid one exists.

Leave both force options off for a fresh machine; the first deploy installs nginx and issues a certificate anyway. They are meant for a host that already carries nginx or certificates from a previous life. Both switch themselves back off after a successful deploy.

What happens after you click Add Server

1. CICDoo connects over SSH and queues a preparation job that installs Docker, nginx, the certificate tooling and the monitoring agent.
2. This usually takes a few minutes. Follow it on the Queue page, which is also where any failure is reported, see Deployments and the job queue.
3. Once the server is ready, you can assign it to a project as its production, staging or development target.

The server appears on the Servers page with its status and resource usage. If the preparation job fails, see Troubleshooting: cannot connect a server.

Related: Server domains and DNS, Using a load balancer, Server actions: deploy, logs and charts, Deleting a server.

If you get stuck, open a support ticket from the Tickets page or the chat widget.