A comic archive browser and reader.
You may browse a live demo server to get a feel for Codex.
Codex has a NEWS file to summarize changes that affect users.
Run the official Docker Image. Instructions for running the docker image are on the Docker Hub README. This is the recommended way to run Codex.
You'll then want to read the Administration section of this document.
You can also run Codex as a natively installed python application with pip.
You'll need to install these system dependencies before installing Codex.
brew install jpeg libffi libyaml libzip openssl python unrar webp
...and Ubuntu, Mint, MX and others (and WSL).
apt install build-essential libimagequant0 libjpeg-turbo8 libopenjp2-7 libssl libyaml-0-2 libtiff6 libwebp7 python3-dev python3-pip mupdf unrar zlib1g
Versions of packages like libjpeg, libssl, libtiff may differ between flavors and versions of Debian. If the version above is not available, try searching for one that is with apt-cache or aptitude.
apt-cache search libjpeg-turbo
apk add bsd-compat-headers build-base jpeg-dev libffi-dev libwebp openssl-dev yaml-dev zlib-dev
Codex requires unrar to read CBR formatted comic archives. Unrar is often not packaged for Linux, but here are some instructions: How to install unrar in Linux
Unrar as packaged for Alpine Linux v3.14 seems to work on Alpine v3.15+
Windows users should use Docker to run Codex until this documentation section is complete.
Codex can probably run on the Windows Linux Subsystem but I haven't personally tested it yet. Try following the instructions for Debian above. There may be outstanding platform related bugs.
Contributions to the Windows documentation will be gratefully accepted on the outstanding issue or Discord.
You may now install Codex with pip
pip3 install codex
pip should install the codex binary on your path. Run
codex
and then navigate to http://localhost:9810/
If you have a HomeAssistant server, Codex can be installed with the following steps :
https://github.com/alexbelgium/hassio-addons
repository by
clicking hereThe first thing you should do is log in as the admin user and change the admin password.
The second thing you will want to do is log in as an Administrator and add one or more comic libraries.
If you forget all your superuser passwords, you may restore the original default
admin account by running codex with the CODEX_RESET_ADMIN
environment variable
set.
CODEX_RESET_ADMIN=1 codex
or, if using Docker:
docker run -e CODEX_RESET_ADMIN=1 -v host-parent-dir/config:/config ajslater/codex
In the Admin Panel you may configure private libraries that are only accessible to specific groups.
A library with no groups is accessible to every user including anonymous users.
A library with any groups is accessible only to users who are in those groups.
Use the Groups admin panel to create groups and the Users admin panel to add and remove users to groups.
Codex can make groups for libraries that exclude groups of users or exclude everyone and include only certain groups of users.
Codex reads PDF metadata from the filename, PDF metadata fields and also many
formats of common complex comic metadata if they are embedded in the PDF
keywords
field.
If you decide to include PDFs in your comic library, I recommend taking time to rename your files so Codex can find some metadata. Codex recognizes several file naming schemes. This one has good results:
{series} v{volume} #{issue} {title} ({year}) {ignored}.pdf
Complex comic metadata, such as ComicInfo.xml, can be also be embedded in the keywords field by using the comicbox command line tool. Codex will read this data because it relies on comicbox internally. Not many people use comicbox or embedded metadata in PDFs in this fashion, so you likely won't find it unless you've added it yourself.
Codex has a limited number of API endpoints available with API Key Access. The API Key is available on the admin/stats tab.
The default config directory is config/
directly under the working directory
you run codex from. You may specify an alternate config directory with the
environment variable CODEX_CONFIG_DIR
.
The config directory contains a file named hypercorn.toml
where you can
specify ports and bind addresses. If no hypercorn.toml
is present Codex copies
a default one to that directory on startup.
The default values for the config options are:
bind = ["0.0.0.0:9810"]
quick_bind = ["0.0.0.0:9810"]
root_path = "/codex"
The config directory also holds the main sqlite database, the Whoosh search index, a Django cache and comic book cover thumbnails.
TIMEZONE
or TZ
will explicitly set the timezone in long format (e.g.
"America/Los Angeles"
). This is useful inside Docker because codex cannot
automatically detect the host machine's timezone.CODEX_CONFIG_DIR
will set the path to codex config directory. Defaults to
$CWD/config
CODEX_RESET_ADMIN=1
will reset the admin user and its password to defaults
when codex starts.CODEX_SKIP_INTEGRITY_CHECK=1
will skip the database integrity repair that
runs when codex starts.DEBUG_TRANSFORM
will show verbose information about how the comicbox library
reads all archive metadata sources and transforms it into a the comicbox
schema.LOGLEVEL
will change how verbose codex's logging is. Valid values are
ERROR
, WARNING
, INFO
, DEBUG
. The default is INFO
.CODEX_LOG_DIR
sets a custom directory for saving logfiles. Defaults to
$CODEX_CONFIG_DIR/logs
CODEX_LOG_TO_FILE=0
will not log to files.CODEX_LOG_TO_CONSOLE=0
will not log to the console.Codex contains some experimental throttling controls. The value supplied to these variables will be interpreted as the maximum number of allowed requests per minute. For example, the following settings would limit each described group to 2 queries per second.
CODEX_THROTTLE_ANON=30
Anonymous usersCODEX_THROTTLE_USER=30
Authenticated usersCODEX_THROTTLE_OPDS=30
The OPDS v1 & v2 APIs (Panels uses this for search)CODEX_THROTTLE_OPENSEARCH=30
The OPDS v1 Opensearch APInginx is often used as a TLS terminator and subpath proxy.
Here's an example nginx config with a subpath named '/codex'.
# HTTP
proxy_set_header Host $http_host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Host $server_name;
proxy_set_header X-Forwarded-Port $server_port;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Scheme $scheme;
# Websockets
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "Upgrade" location /codex {
proxy_pass http://codex:9810;
# Codex reads http basic authentication.
# If the nginx credentials are different than codex credentials use this line to
# not forward the authorization.
proxy_set_header Authorization "";
}
Specify a reverse proxy sub path (if you have one) in config/hypercorn.toml
root_path = "/codex"
Nginx requires a special trick to refresh dns when linked Docker containers recreate. See this nginx with dynamix upstreams article.
Codex can run with as little as 1GB available RAM. Large batch jobs โlike importing and indexing tens of thousands of comics at onceโ will run faster the more memory is available to Codex. The biggest gains in speed happen when you increase memory up to about 6GB. Codex batch jobs do get faster the more memory it has above 6GB, but with diminishing returns.
If you must run Codex in an admin restricted memory environment you might want to temporarily give Codex a lot of memory to run a very large import job and then restrict it for normal operation.
Once your administrator has added some comic libraries, you may browse and read comics. Codex will remember your preferences, bookmarks and progress in the browser session. Codex destroys anonymous sessions and bookmarks after 60 days. To preserve these settings across browsers and after sessions expire, you may register an account with a username and password. You will have to contact your administrator to reset your password if you forget it.
Codex supports OPDS syndication and OPDS streaming. You may find the OPDS url in the side drawer. It should take the form:
http(s)://host.tld(:9810)(/root_path)/opds/v1.2/
or
http(s)://host.tld(:9810)(/root_path)/opds/v2.0/
OPDS 2.0 support is experimental and not widely or well supported by clients. OPDS 2.0 book readers exist, but I am not yet aware of an OPDS 2.0 comic reader.
Kybook 3 does not seem to support http basic authentication, so Cbbodex users are not supported.
If you wish to access OPDS as your Codex User. You will have to add your username and password to the URL. Some OPDS clients do not asssist you with authentication. In that case the OPDS url will look like:
http(s)://username:password@host.tld(:9810)(/root_path)/opds/v1.2/
Codex collects its logs in the config/logs
directory. Take a look to see what
th e server is doing.
You can change how much codex logs by setting the LOGLEVEL
environment
variable. By default this level is INFO
. To see more verbose messages, run
codex like:
LOGLEVEL=DEBUG codex
Codex tries to watch for filesystem events to instantly update your comic
libraries when they change on disk. But these native filesystem events are not
translated between macOS & Windows Docker hosts and the Docker Linux container.
If you find that your installation is not updating to filesystem changes
instantly, you might try enabling polling for the affected libraries and
decreasing the poll_every
value in the Admin console to a frequency that suits
you.
If the database becomes corrupt, Codex includes a facitlity to rebuild the
database. Place a file named rebuild_db
in your Codex config directory like
so:
touch config/rebuild_db
Shut down and restart Codex.
The next time Codex starts it will back up the existing database and try to
rebuild it. The database lives in the config directory as the file
config/db.sqlite3
. If this procedure goes kablooey, you may recover the
original database at config/db.sqlite3.backup
.
Issues and feature requests are best filed on the Github issue tracker.
Codex is a Django Python webserver with a VueJS front end.
/codex/codex/
is the main django app which provides the webserver and
database.
/codex/frontend/
is where the vuejs frontend lives.
Most of Codex development is now controlled through the Makefile. Type make
for a list of commands.
By the generosity of the good people of
Mylar, I and other Codex users answer
questions on the Mylar Discord. Please use the
#codex-support
channel to ask for help with Codex.