---
url: /guide/installation.md
description: Prepare your computer and server to run DockIY.
---

# Installation

DockIY needs:

* a Linux server with a public IP address and SSH access
* a computer where you can run Docker and the DockIY CLI

## 1. Set up DNS

At your DNS provider, point each hostname you will use to your server's public
IP address. For example:

| Hostname | Record | Value |
| --- | --- | --- |
| `example.com` | `A` | your server's IPv4 address |
| `umami.example.com` | `A` | your server's IPv4 address |
| `dozzle.example.com` | `A` | your server's IPv4 address |
| `beszel.example.com` | `A` | your server's IPv4 address |

You may also use a single wildcard `A Record` for subdomains.

## 2. Prepare the server

Allow incoming TCP traffic on ports 22, 80, and 443 in your hosting provider's
firewall. Connect to the server as `root`:

```bash
ssh root@your-server
```

### Debian-based distributions

Install Docker Engine and Docker Compose by following the instructions for
your distribution:

* [Debian](https://docs.docker.com/engine/install/debian/)
* [Ubuntu](https://docs.docker.com/engine/install/ubuntu/)

Then install rsync and start Docker:

```bash
apt update
apt install -y rsync
systemctl enable --now docker
```

Create the deployment user with a home directory and give it Docker access (any user name works):

```bash
adduser dockiy
usermod -aG docker dockiy
```

Add your computer's public ssh key to the server to get passwordless SSH access by following the
[Ubuntu SSH key instructions](https://ubuntu.com/server/docs/how-to/security/openssh-server/#ssh-keys).

Verify the installation from your computer:

```bash
ssh dockiy@your-server 'docker compose version && rsync --version | head -n 1'
```

::: warning Docker access

Membership in the `docker` group gives root-level control of the server. Only
add trusted users.

:::

::: tip Other Linux distributions

Other distributions work. Follow your distribution's instructions for
installing Docker, Docker Compose, and rsync, then create the `dockiy` user and
give it Docker access as shown above.

:::

See the [rsync download and installation information](https://rsync.samba.org/download.html)
for other ways to install rsync.

## 3. Prepare your computer

Install these tools on the computer where you will run DockIY. Use the
instructions for your operating system:

* [Docker](https://docs.docker.com/get-started/get-docker/), including
  [Docker Compose](https://docs.docker.com/compose/install/)
* [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
* [SOPS](https://getsops.io/docs/installation/)
* [age](https://github.com/FiloSottile/age#installation) (only needed to create an age identity)
* an [OpenSSH client](https://www.openssh.com/portable.html) and
  [rsync](https://rsync.samba.org/download.html), if they are not already
  installed

### SOPS identity

Already have an SSH key? SOPS uses `~/.ssh/id_ed25519` or `~/.ssh/id_rsa`
automatically; no conversion or additional identity setup is needed. Select
its public recipient for the getting-started commands:

```bash
export SOPS_RECIPIENT="$(cat ~/.ssh/id_ed25519.pub)" # or ~/.ssh/id_rsa.pub
```

Alternatively, create an age identity once:

```bash
mkdir -p ~/.config/sops/age
age-keygen -o ~/.config/sops/age/keys.txt
export SOPS_AGE_KEY_FILE="$HOME/.config/sops/age/keys.txt"
export SOPS_RECIPIENT="$(age-keygen -y "$SOPS_AGE_KEY_FILE")"
```

Run the getting-started commands in the same shell. Keep private keys out of
Git and off the server, and back them up securely. See [SOPS age and SSH
identities](https://getsops.io/docs/usage/identities/age/) for default paths and
custom identities. For [other SOPS identities](https://getsops.io/docs/usage/identities/),
pass your existing rules with `--sops-config /path/to/.sops.yaml` instead of `--sops`.

## 4. Install the DockIY CLI

Prebuilt binaries are available for Linux, macOS, and Windows on AMD64 and
ARM64. Download the latest version for your platform from the [Codeberg releases
page](https://codeberg.org/chris-paganon/DockIY/releases) or the [Forgejo releases
page](https://forgejo.chrispaganon.com/chris-paganon/DockIY/releases). Rename
it to `dockiy` (`dockiy.exe` on Windows), and put it somewhere on your `PATH`, such as
`~/.local/bin`. On Linux and macOS, make the file executable with `chmod +x
dockiy`.

Then check it:

```bash
dockiy --help
```

Continue with [Get started](/guide/get-started).