Kopia on AWS User Guide

Overview

This image runs Kopia, the fast and secure open source backup and restore tool. Kopia creates encrypted, compressed and globally deduplicated snapshots of your files and directories and stores them in a repository that can live on a filesystem, on cloud object storage such as Amazon S3, or on a Kopia repository server. The image delivers Kopia in server mode with its browser based web UI, so a production grade backup server is running within minutes of launch.

The Kopia binary is installed under /opt/kopia and runs as a dedicated unprivileged kopia system account under a systemd service that starts it on boot and restarts it on failure. The Kopia config, the content cache and a demo filesystem repository all live under /var/lib/kopia, which is a dedicated, independently resizable EBS data volume.

The Kopia server binds to the loopback interface only and is never exposed directly. An nginx reverse proxy publishes the web UI on port 80. Kopia provides its own HTTP Basic authentication, so access to the UI and the repository API is gated by a web UI password that is generated on the first boot of every deployed instance, along with a server control password and a repository password. Two instances launched from the same Amazon Machine Image never share a password. The credentials are written to /root/kopia-credentials.txt with mode 0600 so that only the root user can read them.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network and port 80 for the web UI
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for Kopia. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of t3.small or larger. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that opens port 22 from your management network and port 80 for the web UI. Leave the root volume at the default size or larger.

Select Launch instance. First boot initialisation takes a few seconds after the instance state becomes Running and the status checks pass.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg Kopia Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens ports 22 and 80 as described above.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type t3.small \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=kopia}]'

When the instance reaches the Running state and its status checks pass, note its public IP address or DNS name from the EC2 console or with aws ec2 describe-instances.

Step 3: Connect to Your Instance

Connect over SSH using your key pair and the login user for your operating system variant.

ssh -i <key-name>.pem ubuntu@<public-ip>

Step 4: Retrieve the Credentials

The web UI password is unique to your instance and was generated on first boot. Read the credentials file as root:

sudo cat /root/kopia-credentials.txt

The file lists the web UI URL, the web UI user (admin) and the generated password, the server control credentials, and the password of the demo filesystem repository. Keep these somewhere safe.

Step 5: Sign In to the Kopia Web UI

The Kopia web UI is served on port 80 by nginx in front of the Kopia server, which provides its own HTTP Basic authentication. In a browser, go to:

http://<instance-public-ip>/

You are prompted for credentials. Sign in as admin with the password from the credentials file. The UI opens onto the connected demo filesystem repository, where you can browse snapshots, define sources and policies, and restore data.

The Policies view lets you define snapshot retention, compression, scheduling and the files to ignore, both globally and per source.

The Repository view shows the status of the connected repository, its encryption and splitter configuration, and the running tasks.

Step 6: Confirm Kopia Is Running

Over SSH, confirm the Kopia server and the nginx proxy are active and that the ports are listening:

sudo systemctl is-active kopia-server nginx
sudo ss -tlnp | grep -E ':(80|51515) '

You should see both services reported as active, the Kopia server listening on 127.0.0.1:51515 (loopback only), and nginx listening on port 80.

Step 7: The Demo Filesystem Repository

The image ships connected to a demo filesystem repository created at /var/lib/kopia/repo so the server has a repository to show the moment you sign in. Its password is the kopia.repo.password value in the credentials file. Filesystem repositories are ideal for backing up to an attached EBS volume or to an NFS mount.

You can inspect the connected repository from the command line as the kopia service account, pointing the CLI at the same config and cache the server uses:

sudo -u kopia env KOPIA_CONFIG_PATH=/var/lib/kopia/config/repository.config KOPIA_CACHE_DIRECTORY=/var/lib/kopia/cache /opt/kopia/kopia repository status

Step 8: Create Your First Snapshot

In the web UI open the Snapshots view and choose New Snapshot, then enter a path on the instance to back up, for example a documents directory. Kopia takes an encrypted, compressed and deduplicated snapshot and lists it under the source. Subsequent snapshots of the same source are incremental and fast because unchanged content is deduplicated.

You can also snapshot from the command line:

sudo -u kopia env KOPIA_CONFIG_PATH=/var/lib/kopia/config/repository.config KOPIA_CACHE_DIRECTORY=/var/lib/kopia/cache /opt/kopia/kopia snapshot create /usr/share/doc

Step 9: Define Snapshot Policies

Policies control retention, compression, scheduling and which files to ignore. In the Policies view, edit the global policy or a per source policy to keep a number of hourly, daily, weekly, monthly and annual snapshots, enable compression, and set an automatic snapshot interval. Policies are stored in the repository and apply on every snapshot.

Step 10: Connect an Object Storage Repository

For production backups, connect a repository on Amazon S3 or another object store. From the command line you can create an S3 repository, replacing the placeholders with your bucket and credentials:

sudo -u kopia env KOPIA_CONFIG_PATH=/var/lib/kopia/config/repository.config KOPIA_CACHE_DIRECTORY=/var/lib/kopia/cache KOPIA_PASSWORD='<your-repository-password>' /opt/kopia/kopia repository create s3 --bucket <your-bucket> --access-key <your-access-key> --secret-access-key <your-secret-key>

After connecting a new repository, restart the server with sudo systemctl restart kopia-server so the UI reflects it. Prefer an EC2 instance role over static keys where possible, and grant the instance an IAM role with access to the backup bucket.

Step 11: Restore Data

To restore, open a snapshot in the web UI, browse its directory tree, and download a file or restore a directory to a chosen path. From the command line you can mount a snapshot or restore it directly:

sudo -u kopia env KOPIA_CONFIG_PATH=/var/lib/kopia/config/repository.config KOPIA_CACHE_DIRECTORY=/var/lib/kopia/cache /opt/kopia/kopia snapshot list

Pick a snapshot ID from the list and restore it to a target directory with kopia restore <snapshot-id> <target-path>.

Step 12: The Data Volume

The Kopia config, the content cache and the demo repository live on a dedicated EBS volume mounted at /var/lib/kopia. This keeps the backup state off the operating system disk and lets you resize or snapshot it independently. Confirm the mount with:

df -h /var/lib/kopia

To grow the volume, expand the EBS volume in the AWS console, then grow the filesystem on the instance with sudo resize2fs on the underlying device.

Step 13: Enable HTTPS

The web UI is served over plain HTTP on port 80 by nginx. For production use, place it behind TLS. Obtain a certificate for your domain (for example with a managed certificate on an Application Load Balancer in front of the instance, or with Certbot installed on the instance), then configure nginx to listen on 443 with your certificate and proxy to 127.0.0.1:51515 exactly as the bundled site does for port 80. Restrict the security group so ports 80 and 443 are reachable only from the networks that operate the backup server.

Step 14: The Server Control API

The Kopia server exposes a control API on the same port behind the server control credentials, which is useful for monitoring and automation. The control API does not require a browser CSRF token. Query the connected repository status with the control user:

CTRL=$(sudo grep '^kopia.control.pass=' /root/kopia-credentials.txt | cut -d= -f2-); curl -s -u "server-control:${CTRL}" http://127.0.0.1/api/v1/control/status

Step 15: Backup and Maintenance

Kopia performs its own repository maintenance automatically. Back up a filesystem repository by snapshotting the /var/lib/kopia EBS volume, and back up an object storage repository by relying on the durability of the object store. Apply operating system security updates with sudo apt-get update && sudo apt-get upgrade and reboot when a new kernel is installed; Kopia and nginx start automatically on boot.

Support

This image is published and supported by cloudimg. Support covers deployment, repository configuration on filesystem and object storage, snapshot policies and scheduling, retention and compression tuning, the repository server mode, TLS and restore workflows. Contact cloudimg through the support channel listed on the AWS Marketplace listing.

All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.