Skip to content
ComicLib is a web-based Comics Library that provides a REST API for client apps. ComicLib is still unstable and will become stable as soon as Coboli - the comic reader app based on ComibLib - hits version 1.0.
CSS PHP JavaScript Python HTML Dockerfile
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
Documentation
config
docker/php
mysql-data
src
.gitignore
LICENSE
README.md
amd64.yaml
armhf.yaml
manage.py

README.md

ComicLib

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.

Disclaimer

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

Study paper

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).

Screenshots

Responsive Design
Volumes Overview Volume Details Search For Volumes By Name
Publishers Overview Publisher Details Admins can add users and every user can change his password and API key.
Read your comics in ComicLib. Keep track of the comics you started reading. Update status is visible to all users.

Getting started with ComicLib

  • Install docker and docker-compose. ComicLib uses Docker to run the database- and web-servers as a virtualized environment.
  • Install 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 ./manage.py

Your ComicLib instance will now be accessible via http://127.0.0.1:8081 and https://127.0.0.1:8082 on the computer running ComicLib. Have a look into Security to secure your ComicLib instance.

Server Control

  • start the server by running manage.py or manage.py start
  • to stop the server just run manage.py stop

Security

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 manage.py renew-le.

Server Autostart

If you want to automatically start ComicLib when starting your computer, you can e.g. create a cron job that runs manage.py.

Comics Organization

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.

Testing Data

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.

Additional Information

Comicvine API

ComicLib uses the Comicvine API. Cover images and additional information on your comics will be downloaded from there.

External Libraries

This project makes use of the following libraries (that are not included in PHP):

ComicLib Icon

The ComicLib icon is based on the archive.svg icon from FontAwesome (CC BY 4.0 License).

Legacy Software

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.

You can’t perform that action at this time.