Home assistant addon : Ubooquity (=Plex for books and comics)

Supports aarch64 Architecture Supports amd64 Architecture Supports armhf Architecture Supports armv7 Architecture

Hi, I’ve create an addon for my use and wanted to share it if it can be useful to other people :wink:


Ubooquity by vaemendis is a free, lightweight and easy-to-use home server for your comics and ebooks developed . This addon is based on the docker image from linuxserver.io.

Ubooquity supports many types of files, with a preference for ePUB, CBZ, CBR and PDF files. Metadata from library management software Calibre and ComicRack are also supported. Ubooquity lets you create user accounts and set access rights for each shared folder.

This addons has several configurable options :

  • allowing to mount local external drive, or smb share from the addon (decreases performance)
  • VERY IMPORTANT, CAN CRASH SYSTEM : Setting of the maximum RAM usage for java. The quantity of memory allocated to Ubooquity depends on the hardware your are running it on. If this quantity is too small, you might sometime saturate it with when performing memory intensive operations and you’ll get “java.lang.OutOfMemoryError: Java heap space errors”. If the quantity allocated is too high for your system, it will crash home assistant and you’ll need to manually reboot. Value is a number of megabytes ( put just a number, without MB).

It is recommended to enable OPDS server from option, then you can connect to your comics/eBook server from a mobile app (I use Chunky on iOS (paid), Kuboo on android (free))


The installation of this add-on is pretty straightforward and not different in comparison to installing any other add-on.

  1. Add my Hass.io add-ons repository to your home assistant instance.
  2. Install this add-on.
  3. Click the Save button to store your configuration.
  4. Set the add-on options to your preferences
  5. Start the add-on.
  6. Check the logs of the add-on to see if everything went well.
  7. Open the webUI, set an admin password and adapt the administration options


Admin webui can be found at http://your-ip:2203.
Library webui can be found at http://your-ip:2202. You can also access it by clicking on the ubooquity logo at top left of the admin page, or use a mobile app (preferred option, see above for instructions)
The default username/password : described in the startup log.
Configurations can be done through the app webUI, except for the following options

Network disk is mounted to /mnt/share name

GUID: user
GPID: user
maxmem: 200 # IMPORTANT read above. 200 is default for rpi3b+ ; 512 recommended if more 2gb RAM. 
networkdisks: "<//SERVER/SHARE>" # list of smbv2/3 servers to mount (optional)
cifsusername: "username" # smb username (optional)
cifspassword: "password" # smb password (optional)
smbv1: false # Should smbv1 be used instead of 2.1+?


1 Like

Great addon. I was looking into installing something for my ebooks and then I stumbled over this.

Sadly it wont work over ssl without keystore and I have yet to find a good way of importing my lets encrypt certificate. Until I figure that out the addon will lie dormant because I really cant integrate it anywhere (not even into a custom panel).

Anyone got a solution for the ssl probem?

Also I couldn’t really find what the GUID and GPID are for :thinking:

Thanks! Well then I could implement a nginx server to serve https, I’ll look at that!

GUID means group id and PUID is the user id, it is used to run the container into something else than root. I don’t personaly use it, but here is more documentation : Understanding PUID and PGID - LinuxServer.io

1 Like

that would be awesome

Hello, ssl is enable for ubooquity in the latest update. It is possible to access the UI through http(or https)://YOURIP:2202/ubooquity ; and the admin interface through http(or https)://YOURIP:2203/ubooquity/admin

1 Like

Thanks so much for this add on. I’m really looking forward to using it! I seem to be running into issues with the nginx server, unfortunately. I currently have the nginx ssl proxy configured for enabling local http and external https. When starting this add on, I am getting this message:

[22:24:09] INFO: Starting NGinx...
nginx: [emerg] invalid port in "" of the "listen" directive in /etc/nginx/servers/ingress.conf:2
20211129 22:24:09 [Thread-2] INFO  com.ubooquity.b - Stopping internal server...
20211129 22:24:09 [Thread-2] INFO  com.ubooquity.data.feeder.a - Aborting content scan...

Any suggestions or ideas would be greatly appreciated!

1 Like

Oh I see the issue. I started enabling ingress, but to enable it there would have been a breaking change so I stopped and some files remained. I’ll push a new version now

Just updated. That did the trick. Thanks so much for the quick fix!

1 Like

First of all: Thank you! So awesome that you implemented ssl that quickly. Sadly I get an Error when I try to access the admin interface


Problem accessing /ubooquity/admin. Reason:

    Could not find matching provider (wrong URL)

Any idea why that could be the case?

1 Like

Could you please update the addon, delete the preference.conf in the /config/ubooquity folder and restart? Thanks!

Deleting the preferences.json did the trick

1 Like

I tested implementing ingress and it messed up a few things. It will be stable again thanks for the feedback

the frontend link to the books subfolder seems to be broken for me. The “latest” subsub folder works though

not sure to understand, could you describe a bit more? it is only with ssl enabled, or without, or both? thanks!

only with ssl enabled. I get the error 400 Bad Request The plain HTTP request was sent to HTTPS port. Alle the other dashboard links (comics, latest comics, latest books) work on ssl

1 Like

I’ll look at it, thanks. There is a risk that it is a coding mistake from ubooquity though…

It’s strange, I can’t replicate. Here are the individual pages, they all work for me. Could it be a cache issue on your browser ?

Main page :
Comics :
Books :
Raw :
Latest :
Latest :

And they all open with ssl…


In my home assistant log I found:

21-12-11 20:00:51 ERROR (SyncWorker_0) [supervisor.docker.addon] Add-on Ubooquity try to access to blocked device sda!
21-12-11 20:00:51 ERROR (SyncWorker_0) [supervisor.docker.addon] Add-on Ubooquity try to access to blocked device sda1!

Maybe thats relevant?

It just means that there is no hdd connected available with the name sda… Not sure what you could try. With which url are you accessing the main dashboard? YOURIP:YOURPORT/ubooquity/?

I kinda solved it. But first:

The admin dashboard is accessible via myip:myport/ubooquity/admin
The normal dashboard ist accessible via myip:2202/ubooquity/

I found two problems:

  • When I am in the admin dashboard and click the logo it sends me to myip:2205/ubooquity/ which errors out because its the wrong port
  • When I have Bypass single root folder enabled I cant open my books folder from dashboard (my initaial problem)
1 Like