> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shipways.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Connecting a server

> What Shipways needs, what it does to the machine, and what to do when it stops.

Shipways does not buy machines. You rent one from a provider, and Shipways
takes it over.

## What the machine has to be

A **fresh Ubuntu 22.04 or 24.04 machine** reachable over SSH as root.

Provisioning replaces the SSH, firewall and web server configuration. Point it
at a machine that is already serving something and it will stop serving it. If
you have a box you care about, connect a new one and move the sites across.

## The form

**Name** is how the server appears in Shipways. It does not change the
machine's hostname, and you can change it later.

**IP address** and **SSH port** are how the bootstrap is reached.

**Private IP address** is optional and is used for traffic between your own
machines — an application server reaching a database server. It is also what
[server connections](/servers/settings#private-connections) work in terms of,
so a database server with no private address recorded cannot be let in to.

**What it is for** decides what gets installed and cannot be changed
afterwards. See [server types](/servers/types).

**PHP version** is only asked for when the type runs PHP. More can be
[installed later](/servers/php), so this is a starting point rather than a
commitment.

## The bootstrap command

Once the server is recorded the panel shows a command to run on the machine as
root. It fetches the agent and registers it.

The link inside it is signed and expires in **two hours**. Reload the page for
a fresh one.

Nothing happens until the agent reports in. When it does, the page moves on by
itself and provisioning starts — you do not have to press anything.

## What provisioning does

<Steps>
  <Step title="Verify the operating system">
    A release Shipways knows how to configure, or it stops here.
  </Step>

  <Step title="Create the deploy user">
    An account with sudo, holding the organization's
    [SSH keys](/servers/ssh-keys) in its `authorized_keys`. Sites are served
    from this account's home directory and deploy scripts run as it.
  </Step>

  <Step title="Secure SSH access">
    Password authentication off, root login by key only. Written as a drop-in
    under `/etc/ssh/sshd_config.d/` rather than by editing `sshd_config`, so an
    OS upgrade that replaces the distributed config does not quietly undo it.
    The config is validated before the reload, because a bad one plus a reload
    locks everybody out.
  </Step>

  <Step title="Configure the firewall">
    `ufw` denying everything inbound, plus `fail2ban`. The ports opened depend
    on the type: a machine that serves HTTP starts with 80 and 443, and one
    that does not gets neither. See [the firewall](/servers/firewall).
  </Step>

  <Step title="Install base packages">
    git, curl, zip, logrotate and the rest, plus unattended upgrades limited to
    **security updates only** — a PHP or database point release restarting
    services underneath a running application is not something to do
    unattended. Automatic reboots are off.
  </Step>

  <Step title="Install what the type calls for">
    Nginx, PHP-FPM with Composer and Node.js, Supervisor, Redis, Meilisearch —
    whichever of those the type says the machine is for.
  </Step>
</Steps>

Every step streams its output while it runs, and the whole thing is a task you
can go back to.

## When it fails

The step that failed is the one to read. Provisioning is idempotent enough that
the usual answer to a failure caused by something transient — a package mirror
having a bad minute — is to destroy the machine at your provider and connect a
fresh one. That is cheaper than reasoning about what got half-installed.

## Removing a server

Under **Settings**, removing a server uninstalls the agent and takes the server
and its sites out of Shipways. **Nothing on the machine is deleted.** Nginx,
PHP, your databases and your files stay exactly as they are, and you go on
paying for the machine until you destroy it at your provider.

Archiving is the softer version: the server stops appearing in the ordinary
lists without anything happening to it.