ComicLib is a self-hosted personal comics library. It is a web-app, so you can view and download your comics collection on your PC, smartphone or tablet via your preferred internet browser. ComicLib can use any digital comic book format. It can extract and display comic books if they use the CBZ, CBR or pdf file format. You can download your comic files via ComicLib, so you can use another app on your device to open files which ComicLib can not extract. ComicLib keeps track of which comics you have or have not read, as well as the page you last read (for CBZ, CBR and pdf). To provide additional informations around your comics, ComicLib makes use of the ComicVine comics database. You need a ComicVine user account to use ComicLib.
Aside from the web-app, ComicLib also exposes a RESTful API for 3rd party apps.
The Coboli comic-reader app uses ComicLib as the server that manages and provides the comics for Coboli.
ComicLib is a complete rewrite of ComicDB, adding many new features and a better software architecture and usability.
This software is still in alpha stage. It contains all features planned for version 1 and passed basic testing (using the included example library). It is currently in extended testing (testing against my private library to find bugs that may not occur when using the example library). This readme will be updated at the time version 1 is released.
The ComicLib API version 1 may still change, as the development of Coboli may require changes. Have a look at the API documentation if something breaks. API version 1 will become stable with the release of ComicLib version 1.0, which will be released alongside Coboli version 1.0.
Todo before the release of version 1.0
- Upgrade the docker php image to php 7.3
- Wait for Coboli 1.0
The development of the first prototype of ComicLib was part of the study paper that I wrote as the pre-condition to my bachelor's thesis. The study paper is licensed under the terms and conditions of the CC BY 4.0 license to the TH Köln and can be accessed via the e-publications server of the TH Köln (german).
Getting started with ComicLib
docker-compose. ComicLib uses Docker to run the database- and web-servers as a virtualized environment.
python3. ComicLib uses python for the server manager script. If you want to host ComicLib on Linux, python3 is probably pre-installed.
- Copy or link your comic directories to src/comics
- Open config/ComicLib/config.ini and change the following settings:
- Set safe (and different!) passwords for MYSQL_ROOT_PASSWORD, MYSQL_PASSWORD and AUTH_PASSWORD (which is the password for you web login)
- Set TZ to your timezone. Make sure you use a valid timezone value.
- Get an API key for the Comicvine API from https://comicvine.gamespot.com/api/ and use it as API_KEY
- Start your ComicLib server with
- start the server by running
- to stop the server just run
ComicLib can be accessed via HTTP on port 8081 and via HTTPS via 8082. If using HTTP, your password is send to the ComicLib server in plain text with no additional encryption. This is very insecure and you should really consider using HTTPS instead.
HTTPS is enabled by default, but you will get a certificate warning every time you open ComicLib. To get rid of the warning, you have to request a TLS certificate that matches your domain name.
To get a working TLS certificate, run
manage.py setup-le. This will start Let's Encrypt Certbot, which will guide you through the rest of the process.
To renew your existing certificate, run
If you want to automatically start ComicLib when starting your computer, you can e.g. create a cron job that runs manage.py.
To get familiar with the way ComicLib expects you to organize your comics, please take a look at the included testing data and the ComicVine wiki.
Supported File Formats
ComicLib can handle any file format you throw at it, but only the file formats CBR, CBZ and pdf can be extracted for the reading mode. Thus, files of every other format can only be downloaded from ComicLib, but not read in the web-app. You can e.g. use ComicLib to store your DRM-protected comics and your DRM-free comics in the same collection to get an overview of your whole digital comics collection and which comics you have or have not read yet.
PDF files have to be rendered to single pages when first opening them for reading. This takes much longer than opening CBR or CBZ comic files (minutes vs mere seconds). Consider (batch-)converting your PDF comics to CBR or CBZ before adding them to your ComicLib collection to avoid long loading times when opening one of these comic books.
For testing purposes, ComicLib includes dummy files that will match to some comics. You can use these files to test if your connection to the API works as intended. To prevent these dummies from showing up in your real library after testing, you should delete them from the comics directory and run a database update via the admin dashboard.
The dummy files contain white pages with page numbers 1 to 10 on them, so you can open them in ComicLib to test the reading mode.
ComicLib uses the Comicvine API. Cover images and additional information on your comics will be downloaded from there.
This project makes use of the following libraries (that are not included in PHP):
The ComicLib icon is based on the archive.svg icon from FontAwesome (CC BY 4.0 License).
For compatibility reasons to ARMHF, this project uses MySQL 5.5. This may change as newer versions become available as docker images for ARMHF.
Copyright & License
Copyright (c) 2019 ahahn94.
ComicLib is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.