https://github.com/imagegenius/docker-kopia
https://github.com/imagegenius/docker-kopia
Last synced: 3 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/imagegenius/docker-kopia
- Owner: imagegenius
- License: gpl-3.0
- Created: 2023-01-26T09:17:46.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2026-02-14T04:56:01.000Z (5 months ago)
- Last Synced: 2026-02-14T13:33:15.028Z (5 months ago)
- Language: Dockerfile
- Size: 247 KB
- Stars: 13
- Watchers: 0
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# [imagegenius/kopia](https://github.com/imagegenius/docker-kopia)
[](https://github.com/imagegenius/docker-kopia/releases)
[](https://github.com/imagegenius/docker-kopia/packages)
[](https://ci.imagegenius.io/job/Docker-Pipeline-Builders/job/docker-kopia/job/main/)
[](https://ci-tests.imagegenius.io/kopia/latest-main/index.html)
Kopia is a fast and secure open-source backup/restore tool that allows you to create encrypted snapshots of your data and save the snapshots to remote or cloud storage of your choice, to network-attached storage or server, or locally on your machine.
[](https://kopia.io/)
## Supported Architectures
We use Docker manifest for cross-platform compatibility. More details can be found on [Docker's website](https://distribution.github.io/distribution/spec/manifest-v2-2/#manifest-list).
To obtain the appropriate image for your architecture, simply pull `ghcr.io/imagegenius/kopia:latest`. Alternatively, you can also obtain specific architecture images by using tags.
This image supports the following architectures:
| Architecture | Available | Tag |
| :----: | :----: | ---- |
| x86-64 | ✅ | amd64-\ |
| arm64 | ✅ | arm64v8-\ |
| armhf | ❌ | |
## Application Setup
The WebUI can be found at `http://your-ip:51515`. Login with the username and password specified in the `USERNAME` and `PASSWORD` variables.
The `htpasswd` file is automatically generated on startup (if it does not exist) with the specified username/password in the variables.
After this file has been generated, the `USERNAME`/`PASSWORD` variables can be removed, and the `htpasswd` file can be modified with the `htpasswd` command as desired.
By default, Kopia will be started with the following configuration:
```bash
kopia server start \
--insecure \
--disable-csrf-token-checks \
--address=0.0.0.0:51515 \
--htpasswd-file /config/htpasswd
```
This can be easily overwritten by specifying startup parameters in the `CLI_ARGS` variable, which will overwrite everything after the `kopia` command, eg:
`CLI_ARGS=`
```bash
server start \
--disable-csrf-token-checks \
--tls-cert-file=/config/keys/fullchain.pem \
--tls-key-file=/config/keys/privkey.pem \
--address=0.0.0.0:51515 \
--server-username=kopia \
--server-password=kopia
```
**When specifying `CLI_ARGS`, they must be on a single line.**
If you have entered invalid `CLI_ARGS`, Kopia will not start (see the logs if this happens).
## Usage
Example snippets to start creating a container:
### Docker Compose
```yaml
---
services:
kopia:
image: ghcr.io/imagegenius/kopia:latest
container_name: kopia
hostname: kopia
cap_add:
- SYS_ADMIN
environment:
- PUID=1000
- PGID=1000
- TZ=Etc/UTC
- USERNAME=kopia
- PASSWORD=kopia
- KOPIA_PERSIST_CREDENTIALS_ON_CONNECT=true #optional
- CLI_ARGS= #optional
volumes:
- :/config
- :/source
- :/cache
- :/local #optional
ports:
- 51515:51515
devices:
- /dev/fuse:/dev/fuse
restart: unless-stopped
```
### Docker CLI ([Click here for more info](https://docs.docker.com/engine/reference/commandline/cli/))
```bash
docker run -d \
--name=kopia \
--hostname=kopia \
--cap-add=SYS_ADMIN \
-e PUID=1000 \
-e PGID=1000 \
-e TZ=Etc/UTC \
-e USERNAME=kopia \
-e PASSWORD=kopia \
-e KOPIA_PERSIST_CREDENTIALS_ON_CONNECT=true `#optional` \
-e CLI_ARGS= `#optional` \
-p 51515:51515 \
-v :/config \
-v :/source \
-v :/cache \
-v :/local `#optional` \
--device /dev/fuse:/dev/fuse \
--restart unless-stopped \
ghcr.io/imagegenius/kopia:latest
```
## Parameters
To configure the container, pass variables at runtime using the format `:`. For instance, `-p 8080:80` exposes port `80` inside the container, making it accessible outside the container via the host's IP on port `8080`.
| Parameter | Function |
| :----: | --- |
| `--hostname=` | Set hostname for the container. |
| `-p 51515` | WebUI Port |
| `-e PUID=1000` | UID for permissions - see below for explanation |
| `-e PGID=1000` | GID for permissions - see below for explanation |
| `-e TZ=Etc/UTC` | Specify a timezone to use, see this [list](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List). |
| `-e USERNAME=kopia` | Specify a username to access the WebUI, this can be removed after first setup |
| `-e PASSWORD=kopia` | Specify a password to access the WebUI, this can be removed after first setup |
| `-e KOPIA_PERSIST_CREDENTIALS_ON_CONNECT=true` | Automatically connect to repository |
| `-e CLI_ARGS=` | Overwrite CLI arguments |
| `-v /config` | Appdata Path |
| `-v /source` | Backup Source Path |
| `-v /cache` | Temporary Uploads Path (Cache) |
| `-v /local` | Path for local filesystem repositories |
| `--device /dev/fuse` | Allows fuse mounts to function |
## Umask for running applications
All of our images allow overriding the default umask setting for services started within the containers using the optional -e UMASK=022 option. Note that umask works differently than chmod and subtracts permissions based on its value, not adding. For more information, please refer to the Wikipedia article on umask [here](https://en.wikipedia.org/wiki/Umask).
## User / Group Identifiers
To avoid permissions issues when using volumes (`-v` flags) between the host OS and the container, you can specify the user (`PUID`) and group (`PGID`). Make sure that the volume directories on the host are owned by the same user you specify, and the issues will disappear.
Example: `PUID=1000` and `PGID=1000`. To find your PUID and PGID, run `id user`.
```bash
$ id username
uid=1000(dockeruser) gid=1000(dockergroup) groups=1000(dockergroup)
```
## Updating the Container
Most of our images are static, versioned, and require an image update and container recreation to update the app. We do not recommend or support updating apps inside the container. Check the [Application Setup](#application-setup) section for recommendations for the specific image.
Instructions for updating containers:
### Via Docker Compose
* Update all images: `docker-compose pull`
* or update a single image: `docker-compose pull kopia`
* Let compose update all containers as necessary: `docker-compose up -d`
* or update a single container: `docker-compose up -d kopia`
* You can also remove the old dangling images: `docker image prune`
### Via Docker Run
* Update the image: `docker pull ghcr.io/imagegenius/kopia:latest`
* Stop the running container: `docker stop kopia`
* Delete the container: `docker rm kopia`
* Recreate a new container with the same docker run parameters as instructed above (if mapped correctly to a host folder, your `/config` folder and settings will be preserved)
* You can also remove the old dangling images: `docker image prune`
## Versions
* **24.03.24:** - rebase to alpine edge.
* **22.04.23:** - use `htpasswd` file.
* **21.04.23:** - Add `CLI_ARGS` variable.
* **14.04.23:** - BREAKING: move cache from /tmp to /cache.
* **11.04.23:** - fix run script ('kopia server' to 'kopia server start')
* **28.03.23:** - set home in service
* **23.03.23:** - add fuse package
* **21.03.23:** - Add service checks
* **26.01.23:** - Initial release.