I wanted to pop Kavita on Ubuntu 22.04, with access to my books (a mix of EPUB, CBZ and PDF files) via a Samba share hosted on another server. There are multiple ways to install Kavita, but there isn’t an official package in the Ubuntu repositories. So, rather than faff around with unofficial packages I thought Docker might be the easier option to install Kavita and, most importantly, keep it up to date. This is the story of how I did it.

Samba Share Access

Obviously the first thing you need to do is setup a samba share somewhere. That’s beyond the scope of this particular post, but if you’re interested I used an OpenMediaVault server, and it was super easy.

To connect to a Samba share first of all you need the CIFS utilities package, which contains everything you need to mount a Samba share. Before you go installing that though it’s a good idea to make sure the apt packages list is up to date.

$ sudo apt update

And while you’re at it you might as well upgrade your packages too.

$ sudo apt upgrade

Then install the CIFS utilities package, which lets us mount Samba shares.

$ sudo apt install cifs-utils

Next we need to create and edit a file to store our Samba credentials, so we can connect automatically when the server boots.

$ nano .smbcreds

I use nano for editing this, but really any text editor will do. In this file enter the following details.


Where USERNAME is your Samba username and PASSWORD is your Samba password for the remote share. Then you need to make sure the file is secured and not readable to others.

$ chmod 600 .smbcreds

(you shouldn’t need sudo here, because above you created the file as yourself). Next create the directory you want to mount the share to.

$ sudo mkdir /media/SHARE

Where SHARE is the name you want to mount your share as. Now we need to add a line in fstab to make sure the share is mounted at boot, so edit fstab.

$ sudo nano /etc/fstab

And add the following to the bottom of the file.

//SERVER/SMBSHARE /media/SHARE cifs credentials=/home/USERNAME/.smbcreds,iocharset=utf8 0 0

Where SERVER is the server your share lives on, SMBSHARE is the remote share itself. Once you’ve done that you can test the connection with.

$ sudo mount -a

Which will hopefully mount the share. Do a quick listing of the share’s contents to double check.

$ ls -l /media/SHARE

And there you have it, one remote Samba share mounted and ready for use.


Now it’s time to install Docker, again there are multiple ways to do this but I prefer to use Ubuntu’s official packaged version as it’s easier.

$ sudo apt install docker.io

Once installed most tutorials online will have you start and enable the service, but you don’t have to do any of that as it’s already handled by Ubuntu’s package. Just check the Docker service status to see for yourself.

$ sudo systemctl status docker.service

And check it’s enabled (i.e. will start on boot).

$ sudo systemctl is-enabled docker.service

You can also check various information about Docker to see things like what version you have installed.

$ sudo docker version
$ sudo docker info

Most tutorials will now tell you to enable Docker to run without using sudo, but again that isn’t necessary. Besides, I find the requirement to use sudo gives a nice bit of sanity checking.

Docker Compose

Now, here’s where I do things a little differently to a lot of the Docker tutorials out there. Normally they’d just spin up the image with docker run on the command line, but I’m going to use Docker Compose. I do it this way for a number of reasons, first and foremost because it’s a better way to manage multiple docker images. It can get quite messy quite quickly once you get more than one image on the go. Also, most tutorials seem to consider Compose to be more advanced use, but I find it a much better way to understand what you’re doing with Docker. So, let’s install Docker Compose.

$ sudo apt install docker-compose

Once installed we’ll want to create a directory to keep the compose files in.

$ mkdir compose

Then let’s move into the new directory.

$ cd compose/

And we’ll want a directory to keep the Kavita config files in too.

$ mkdir kavita

Next let’s create a Docker Compose file.

$ nano docker-compose.yml

Into which we place our config.

version: '3.9'
		image: kizaing/kavita:latest
		container_name: kavita
			- /media/SHARE:/books # Samba book share
			- ./kavita/config:/kavita/config # Kavita config location
			- TZ=Europe/London
			- "5000:5000"
		restart: unless-stopped

This names the container kavita, using the latest version of the Kavita Docker image kizaing/kavita:latest. The volumes are the directories we want to share with the container, in this case just the book share from earlier and the Kavita directory we created for the config. You can add more volumes if needed, for example a comics directory. Next is the timezone, Europe/London in my case. The ports you want to use, I’m just passing 5000 on the host through to 5000 on the container, but you can use anything you like here. For example 80:5000 would send HTTP traffic to the host on to the container. Finally, the restart setting makes sure Docker will restart the container unless it’s been explicitly stopped (with sudo docker-compose down).


A quick diversion into timezones, if you need to check your timezone you can use.

$ timedatectl show

and if you need to set it to your timezone then use.

$ sudo timedatectl set-timezone TIMEZONE

Where TIMEZONE is your local timezone, which is Europe/London in my case.

Back to docker, you now need to run your compose file with.

$ sudo docker-compose up -d

And finally we check the container is up and running.

$ sudo docker-compose ps

And there you have it, Kavita on Docker on Ubuntu 22.04. Browse to your server’s IP address on port 5000 (or whatever port you used) and enjoy your book collection.