# Codex
A comic archive browser and reader.
<img src="codex/static_src/img/logo.svg" style="
height: 128px;
width: 128px;
border-radius: 128px;
" />
## <a name="features">β¨ Features</a>
- Codex is a web server.
- GPLv3 Licenced.
- Full text search of metadata and bookmarks.
- Filter and sort on all comic metadata and unread status per user.
- Browse a tree of Publishers, Imprints, Series, Volumes, or your own folder
hierarchy, or by tagged Story Arc.
- Read comics in a variety of aspect ratios and directions that fit your screen.
- Watches the filesystem and automatically imports new or changed comics.
- Anonymous browsing and reading or reigistered users only, to your preference.
- Per user bookmarking & settings, even before you make an account.
- Private Libraries accessible only to certain groups of users.
- Reads CBZ, CBR, CBT, and PDF formatted comics.
- Syndication with OPDS 1 & 2, streaming, search and authentication.
- Add custom covers to Folders, Publishers, Imprints, Series, and Story Arcs.
- Runs in 1GB of RAM, faster with more.
### Examples
- _Filter by_ Story Arc and Unread, _Order by_ Publish Date to create an event
reading list.
- _Filter by_ Unread and _Order by_ Added Time to see your latest unread comics.
- _Search by_ your favorite character to find their appearances across different
comics.
## <a name="demonstration">π Demonstration</a>
You may browse a [live demo server](https://demo.codex-reader.app/) to get a
feel for Codex.
## <a name="news">π News</a>
Codex has a <a href="NEWS.md">NEWS file</a> to summarize changes that affect
users.
## <a name="installation">π¦ Installation</a>
### Install & Run with Docker
Run the official [Docker Image](https://hub.docker.com/r/ajslater/codex).
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](#administration) section of this
document.
### Install & Run on <a href="homeassistant">HomeAssistant</a> server
If you have a [HomeAssistant](https://www.home-assistant.io/) server, Codex can
be installed with the following steps :
- Add the `https://github.com/alexbelgium/hassio-addons` repository by
[clicking here](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Falexbelgium%2Fhassio-addons)
- Install the addon :
[click here to automatically open the addon store, then install the addon](https://my.home-assistant.io/redirect/supervisor)
- Customize addon options, then then start the add-on.
### Install & Run as a Native Application
You can also run Codex as a natively installed python application with pip.
#### Binary Dependencies
You'll need to install the appropriate system dependencies for your platform
before installing Codex.
##### Linux Dependencies
###### <a href="#debian">Debian</a> Dependencies
...and Ubuntu, Mint, MX, Window Subsystem for Linux, and others.
```sh
apt install build-essential libimagequant0 libjpeg-turbo8 libopenjp2-7 libssl libyaml-0-2 libtiff6 libwebp7 python3-dev python3-pip mupdf sqlite3 unrar zlib1g
```
Versions of packages like libjpeg, libssl, libtiff may differ between flavors
and versions of your distribution. If the package versions listed in the example
above are not available, try searching for ones that are with `apt-cache` or
`aptitude`.
```sh
apt-cache search libjpeg-turbo
```
###### <a href="alpine">Alpine</a> Dependencies
```sh
apk add bsd-compat-headers build-base jpeg-dev libffi-dev libwebp openssl-dev sqlite yaml-dev zlib-dev
```
##### Install unrar Runtime Dependency on non-debian Linux
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](https://www.unixtutorial.org/how-to-install-unrar-in-linux/)
Unrar as packaged for Alpine Linux v3.14 seems to work on Alpine v3.15+
##### macOS Dependencies
Using [Homebrew](https://brew.sh/):
```sh
brew install jpeg libffi libyaml libzip openssl python sqlite unrar webp
```
##### <a href="#windows">Windows</a> Dependencies
Windows users are encouraged to use Docker to run Codex, but it will also run
natively on the Windows Subsystem for Linux.
Installation instructions are in the <a href="/WINDOWS.md">Native Windows
Dependencies Installation Document</a>.
#### <a href="#run">Run</a> Codex Natively
Once you have installed codex, the codex binary should be on your path. To start
codex, run:
```sh
codex
```
### Use Codex
Once installed and running you may navigate to <http://localhost:9810/>
## <a name="administration">π Administration</a>
### Navigate to the Admin Panel
- Click the hamburger menu β° to open the browser settings drawer.
- Log in as the 'admin' user. The default administrator password is also
'admin'.
- Navigate to the Admin Panel by clicking on its link in the browser settings
drawer after you have logged in.
### Change the Admin password
The first thing you should do is log in as the admin user and change the admin
password.
- Navigate to the Admin Panel as described above.
- Select the Users tab.
- Change the admin user's password using the small lock button.
- You may also change the admin user's name with the edit button.
- You may create other users and grant them admin privileges by making them
staff.
### Add Comic Libraries
The second thing you will want to do is log in as an Administrator and add one
or more comic libraries.
- Navigate to the Admin Panel as described above.
- Select the Libraries tab in the Admin Panel
- Add a Library with the "+ LIBRARY" button in the upper left.
### Reset the admin password
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.
```sh
CODEX_RESET_ADMIN=1 codex
```
or, if using Docker:
```sh
docker run -e CODEX_RESET_ADMIN=1 -v host-parent-dir/config:/config ajslater/codex
```
### Private Libraries
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.
#### Include and Exclude Groups
Codex can make groups for libraries that exclude groups of users or exclude
everyone and include only certain groups of users.
### PDF Metadata
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](https://github.com/ajslater/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.
### ποΈ API with Key Access
Codex has a limited number of API endpoints available with API Key Access. The
API Key is available on the admin/stats tab.
## <a name="configuration">ποΈ Configuration</a>
### Config Dir
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:
```toml
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.
### Environment Variables
#### General
- `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_FIX_FOREIGN_KEYS=1` will check for and try to repair illegal foreign
keys on startup.
- `CODEX_INTEGRITY_CHECK=1` will perform database integrity check on startup.
- `CODEX_FTS_INTEGRITY_CHECK=1` will perform an integrity check on the full text
search index.
- `CODEX_FTS_REBUILD=1` will rebuild the full text search index.
- `DEBUG_TRANSFORM` will show verbose information about how the comicbox library
reads all archive metadata sources and transforms it into a the comicbox
schema.
#### Logging
- `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.
#### Throttling
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 users
- `CODEX_THROTTLE_USER=30` Authenticated users
- `CODEX_THROTTLE_OPDS=30` The OPDS v1 & v2 APIs (Panels uses this for search)
- `CODEX_THROTTLE_OPENSEARCH=30` The OPDS v1 Opensearch API
### Reverse Proxy
[nginx](https://nginx.org/) is often used as a TLS terminator and subpath proxy.
Here's an example nginx config with a subpath named '/codex'.
```nginx
# 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`
```toml
root_path = "/codex"
```
#### Nginx Reverse Proxy 502 when container refreshes
Nginx requires a special trick to refresh dns when linked Docker containers
recreate. See this
[nginx with dynamix upstreams](https://tenzer.dk/nginx-with-dynamic-upstreams/)
article.
### Restricted Memory Environments
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.
## <a name="use">π Use</a>
### π€ Sessions & Accounts
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.
### α―€ OPDS
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.
#### Clients
- iOS has [Panels](https://panels.app/), [PocketBooks](https://pocketbook.ch/),
[KYBook 3](http://kybook-reader.com/), and
[Chunky Comic Reader](https://apps.apple.com/us/app/chunky-comic-reader/id663567628)
- Android has
[Moon+](https://play.google.com/store/apps/details?id=com.flyersoft.moonreader)
and
[Librera](https://play.google.com/store/apps/details?id=com.foobnix.pdf.reader)
Kybook 3 does not seem to support http basic authentication, so Cbbodex users
are not supported.
#### HTTP Basic Authentication
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/`
#### Supported OPDS Specifications
##### OPDS v1
- [OPDS 1.2](https://specs.opds.io/opds-1.2.html)
- [OPDS-PSE 1.2](https://github.com/anansi-project/opds-pse/blob/master/v1.2.md)
- [OPDS Authentication 1.0](https://drafts.opds.io/authentication-for-opds-1.0.html)
- [OpenSearch 1.1](https://github.com/dewitt/opensearch)
##### OPDS v2
- [OPDS 2.0 (draft)](https://drafts.opds.io/opds-2.0.html)
- [OPDS 2.0 Progression (proposal)](https://github.com/opds-community/drafts/discussions/67)
## <a name="troubleshooting">π©Ί Troubleshooting</a>
### π Logs
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:
```sh
LOGLEVEL=DEBUG codex
```
### Watching Filesystem Events with Docker
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.
### Emergency Database Repair
If the database becomes corrupt, Codex includes a facility to rebuild the
database. Place a file named `rebuild_db` in your Codex config directory like
so:
```sh
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/backups/codex.sqlite3.before-rebuild`. Codex will
remove the `rebuild_db` file.
### Warnings to Ignore
#### StreamingHttpResponse Iterator Warning
```pycon
packages/django/http/response.py:517: Warning: StreamingHttpResponse must consume synchronous iterators in order to serve them asynchronously. Use an asynchronous iterator instead.
```
This is a known warning and does not represent anything bad happening. It's an
artifact of the Django framework slowly supporting asynchronous server endpoints
and unfortunately isn't practical to remove yet.
## <a name="alternatives-to-codex">πAlternatives</a>
- [Kavita](https://www.kavitareader.com/) has light metadata filtering/editing,
supports comics, eBooks, and features for manga.
- [Komga](https://komga.org/) has light metadata editing.
- [Ubooquity](https://vaemendis.net/ubooquity/) reads both comics and eBooks.
- [Mylar](https://github.com/mylar3/mylar3) is the best comic book manager which
also has a built in reader.
- [Comictagger](https://github.com/comictagger/comictagger) is a comic metadata
editor. It comes with a powerful command line and desktop GUI.
## <a name="contributing">π€ Contributing</a>
### <a name="bug_reports">π Bug Reports</a>
Issues and feature requests are best filed on the
[Github issue tracker](https://github.com/ajslater/codex/issues).
### <a name="out-of-scope">π« Out of Scope</a>
- I have no intention of making this an eBook reader.
- I think metadata editing would be better placed in a comic manager than a
reader.
### <a name="develop-codex">π Develop</a>
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.
## <a name="discord">π¬ Support</a>
By the generosity of the good people of
[Mylar](https://github.com/mylar3/mylar3), I and other Codex users answer
questions on the [Mylar Discord](https://discord.gg/6UG94R7E8T). Please use the
`#codex-support` channel to ask for help with Codex.
## <a name="links">π Links</a>
- [Docker Image](https://hub.docker.com/r/ajslater/codex)
- [PyPi Package](https://pypi.org/project/codex/)
- [GitHub Project](https://github.com/ajslater/codex/)
## <a name="special-thanks">ππ» Special Thanks</a>
- Thanks to [AurΓ©lien Mazurie](https://pypi.org/user/ajmazurie/) for allowing me
to use the PyPi name 'codex'.
- To [ProfessionalTart](https://github.com/professionaltart) for providing
native Windows installation instructions.
- Thanks to the good people of
[#mylar](https://github.com/mylar3/mylar3#live-support--conversation) for
continuous feedback and comic ecosystem education.
## <a name="enjoy">π Enjoy</a>
Raw data
{
"_id": null,
"home_page": "https://github.com/ajslater/codex",
"name": "codex",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "comic, cbz, cbr, cbt, pdf",
"author": "AJ Slater",
"author_email": "aj@slater.net",
"download_url": "https://files.pythonhosted.org/packages/ae/93/e9a7c1058c935fbc2112fdc076aa6f3c91436fcf0edb254e2a3e67cc645a/codex-1.7.10.tar.gz",
"platform": null,
"description": "# Codex\n\nA comic archive browser and reader.\n\n<img src=\"codex/static_src/img/logo.svg\" style=\"\nheight: 128px;\nwidth: 128px;\nborder-radius: 128px;\n\" />\n\n## <a name=\"features\">\u2728 Features</a>\n\n- Codex is a web server.\n- GPLv3 Licenced.\n- Full text search of metadata and bookmarks.\n- Filter and sort on all comic metadata and unread status per user.\n- Browse a tree of Publishers, Imprints, Series, Volumes, or your own folder\n hierarchy, or by tagged Story Arc.\n- Read comics in a variety of aspect ratios and directions that fit your screen.\n- Watches the filesystem and automatically imports new or changed comics.\n- Anonymous browsing and reading or reigistered users only, to your preference.\n- Per user bookmarking & settings, even before you make an account.\n- Private Libraries accessible only to certain groups of users.\n- Reads CBZ, CBR, CBT, and PDF formatted comics.\n- Syndication with OPDS 1 & 2, streaming, search and authentication.\n- Add custom covers to Folders, Publishers, Imprints, Series, and Story Arcs.\n- Runs in 1GB of RAM, faster with more.\n\n### Examples\n\n- _Filter by_ Story Arc and Unread, _Order by_ Publish Date to create an event\n reading list.\n- _Filter by_ Unread and _Order by_ Added Time to see your latest unread comics.\n- _Search by_ your favorite character to find their appearances across different\n comics.\n\n## <a name=\"demonstration\">\ud83d\udc40 Demonstration</a>\n\nYou may browse a [live demo server](https://demo.codex-reader.app/) to get a\nfeel for Codex.\n\n## <a name=\"news\">\ud83d\udcdc News</a>\n\nCodex has a <a href=\"NEWS.md\">NEWS file</a> to summarize changes that affect\nusers.\n\n## <a name=\"installation\">\ud83d\udce6 Installation</a>\n\n### Install & Run with Docker\n\nRun the official [Docker Image](https://hub.docker.com/r/ajslater/codex).\nInstructions for running the docker image are on the Docker Hub README. This is\nthe recommended way to run Codex.\n\nYou'll then want to read the [Administration](#administration) section of this\ndocument.\n\n### Install & Run on <a href=\"homeassistant\">HomeAssistant</a> server\n\nIf you have a [HomeAssistant](https://www.home-assistant.io/) server, Codex can\nbe installed with the following steps :\n\n- Add the `https://github.com/alexbelgium/hassio-addons` repository by\n [clicking here](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Falexbelgium%2Fhassio-addons)\n- Install the addon :\n [click here to automatically open the addon store, then install the addon](https://my.home-assistant.io/redirect/supervisor)\n- Customize addon options, then then start the add-on.\n\n### Install & Run as a Native Application\n\nYou can also run Codex as a natively installed python application with pip.\n\n#### Binary Dependencies\n\nYou'll need to install the appropriate system dependencies for your platform\nbefore installing Codex.\n\n##### Linux Dependencies\n\n###### <a href=\"#debian\">Debian</a> Dependencies\n\n...and Ubuntu, Mint, MX, Window Subsystem for Linux, and others.\n\n```sh\napt install build-essential libimagequant0 libjpeg-turbo8 libopenjp2-7 libssl libyaml-0-2 libtiff6 libwebp7 python3-dev python3-pip mupdf sqlite3 unrar zlib1g\n```\n\nVersions of packages like libjpeg, libssl, libtiff may differ between flavors\nand versions of your distribution. If the package versions listed in the example\nabove are not available, try searching for ones that are with `apt-cache` or\n`aptitude`.\n\n```sh\napt-cache search libjpeg-turbo\n```\n\n###### <a href=\"alpine\">Alpine</a> Dependencies\n\n```sh\napk add bsd-compat-headers build-base jpeg-dev libffi-dev libwebp openssl-dev sqlite yaml-dev zlib-dev\n```\n\n##### Install unrar Runtime Dependency on non-debian Linux\n\nCodex requires unrar to read CBR formatted comic archives. Unrar is often not\npackaged for Linux, but here are some instructions:\n[How to install unrar in Linux](https://www.unixtutorial.org/how-to-install-unrar-in-linux/)\n\nUnrar as packaged for Alpine Linux v3.14 seems to work on Alpine v3.15+\n\n##### macOS Dependencies\n\nUsing [Homebrew](https://brew.sh/):\n\n```sh\nbrew install jpeg libffi libyaml libzip openssl python sqlite unrar webp\n```\n\n##### <a href=\"#windows\">Windows</a> Dependencies\n\nWindows users are encouraged to use Docker to run Codex, but it will also run\nnatively on the Windows Subsystem for Linux.\n\nInstallation instructions are in the <a href=\"/WINDOWS.md\">Native Windows\nDependencies Installation Document</a>.\n\n#### <a href=\"#run\">Run</a> Codex Natively\n\nOnce you have installed codex, the codex binary should be on your path. To start\ncodex, run:\n\n```sh\ncodex\n```\n\n### Use Codex\n\nOnce installed and running you may navigate to <http://localhost:9810/>\n\n## <a name=\"administration\">\ud83d\udc51 Administration</a>\n\n### Navigate to the Admin Panel\n\n- Click the hamburger menu \u2630 to open the browser settings drawer.\n- Log in as the 'admin' user. The default administrator password is also\n 'admin'.\n- Navigate to the Admin Panel by clicking on its link in the browser settings\n drawer after you have logged in.\n\n### Change the Admin password\n\nThe first thing you should do is log in as the admin user and change the admin\npassword.\n\n- Navigate to the Admin Panel as described above.\n- Select the Users tab.\n- Change the admin user's password using the small lock button.\n- You may also change the admin user's name with the edit button.\n- You may create other users and grant them admin privileges by making them\n staff.\n\n### Add Comic Libraries\n\nThe second thing you will want to do is log in as an Administrator and add one\nor more comic libraries.\n\n- Navigate to the Admin Panel as described above.\n- Select the Libraries tab in the Admin Panel\n- Add a Library with the \"+ LIBRARY\" button in the upper left.\n\n### Reset the admin password\n\nIf you forget all your superuser passwords, you may restore the original default\nadmin account by running codex with the `CODEX_RESET_ADMIN` environment variable\nset.\n\n```sh\nCODEX_RESET_ADMIN=1 codex\n```\n\nor, if using Docker:\n\n```sh\ndocker run -e CODEX_RESET_ADMIN=1 -v host-parent-dir/config:/config ajslater/codex\n```\n\n### Private Libraries\n\nIn the Admin Panel you may configure private libraries that are only accessible\nto specific groups.\n\nA library with _no_ groups is accessible to every user including anonymous\nusers.\n\nA library with _any_ groups is accessible only to users who are in those groups.\n\nUse the Groups admin panel to create groups and the Users admin panel to add and\nremove users to groups.\n\n#### Include and Exclude Groups\n\nCodex can make groups for libraries that exclude groups of users or exclude\neveryone and include only certain groups of users.\n\n### PDF Metadata\n\nCodex reads PDF metadata from the filename, PDF metadata fields and also many\nformats of common complex comic metadata if they are embedded in the PDF\n`keywords` field.\n\nIf you decide to include PDFs in your comic library, I recommend taking time to\nrename your files so Codex can find some metadata. Codex recognizes several file\nnaming schemes. This one has good results:\n\n`{series} v{volume} #{issue} {title} ({year}) {ignored}.pdf`\n\nComplex comic metadata, such as ComicInfo.xml, can be also be embedded in the\nkeywords field by using the [comicbox](https://github.com/ajslater/comicbox)\ncommand line tool. Codex will read this data because it relies on comicbox\ninternally. Not many people use comicbox or embedded metadata in PDFs in this\nfashion, so you likely won't find it unless you've added it yourself.\n\n### \ud83d\udddd\ufe0f API with Key Access\n\nCodex has a limited number of API endpoints available with API Key Access. The\nAPI Key is available on the admin/stats tab.\n\n## <a name=\"configuration\">\ud83c\udf9b\ufe0f Configuration</a>\n\n### Config Dir\n\nThe default config directory is `config/` directly under the working directory\nyou run codex from. You may specify an alternate config directory with the\nenvironment variable `CODEX_CONFIG_DIR`.\n\nThe config directory contains a file named `hypercorn.toml` where you can\nspecify ports and bind addresses. If no `hypercorn.toml` is present Codex copies\na default one to that directory on startup.\n\nThe default values for the config options are:\n\n```toml\nbind = [\"0.0.0.0:9810\"]\nquick_bind = [\"0.0.0.0:9810\"]\nroot_path = \"/codex\"\n```\n\nThe config directory also holds the main sqlite database, the Whoosh search\nindex, a Django cache and comic book cover thumbnails.\n\n### Environment Variables\n\n#### General\n\n- `TIMEZONE` or `TZ` will explicitly set the timezone in long format (e.g.\n `\"America/Los Angeles\"`). This is useful inside Docker because codex cannot\n automatically detect the host machine's timezone.\n- `CODEX_CONFIG_DIR` will set the path to codex config directory. Defaults to\n `$CWD/config`\n- `CODEX_RESET_ADMIN=1` will reset the admin user and its password to defaults\n when codex starts.\n- `CODEX_FIX_FOREIGN_KEYS=1` will check for and try to repair illegal foreign\n keys on startup.\n- `CODEX_INTEGRITY_CHECK=1` will perform database integrity check on startup.\n- `CODEX_FTS_INTEGRITY_CHECK=1` will perform an integrity check on the full text\n search index.\n- `CODEX_FTS_REBUILD=1` will rebuild the full text search index.\n- `DEBUG_TRANSFORM` will show verbose information about how the comicbox library\n reads all archive metadata sources and transforms it into a the comicbox\n schema.\n\n#### Logging\n\n- `LOGLEVEL` will change how verbose codex's logging is. Valid values are\n `ERROR`, `WARNING`, `INFO`, `DEBUG`. The default is `INFO`.\n- `CODEX_LOG_DIR` sets a custom directory for saving logfiles. Defaults to\n `$CODEX_CONFIG_DIR/logs`\n- `CODEX_LOG_TO_FILE=0` will not log to files.\n- `CODEX_LOG_TO_CONSOLE=0` will not log to the console.\n\n#### Throttling\n\nCodex contains some experimental throttling controls. The value supplied to\nthese variables will be interpreted as the maximum number of allowed requests\nper minute. For example, the following settings would limit each described group\nto 2 queries per second.\n\n- `CODEX_THROTTLE_ANON=30` Anonymous users\n- `CODEX_THROTTLE_USER=30` Authenticated users\n- `CODEX_THROTTLE_OPDS=30` The OPDS v1 & v2 APIs (Panels uses this for search)\n- `CODEX_THROTTLE_OPENSEARCH=30` The OPDS v1 Opensearch API\n\n### Reverse Proxy\n\n[nginx](https://nginx.org/) is often used as a TLS terminator and subpath proxy.\n\nHere's an example nginx config with a subpath named '/codex'.\n\n```nginx\n# HTTP\nproxy_set_header Host $http_host;\nproxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\nproxy_set_header X-Forwarded-Host $server_name;\nproxy_set_header X-Forwarded-Port $server_port;\nproxy_set_header X-Forwarded-Proto $scheme;\nproxy_set_header X-Real-IP $remote_addr;\nproxy_set_header X-Scheme $scheme;\n# Websockets\nproxy_http_version 1.1;\nproxy_set_header Upgrade $http_upgrade;\n\nproxy_set_header Connection \"Upgrade\" location /codex {\n proxy_pass http://codex:9810;\n # Codex reads http basic authentication.\n # If the nginx credentials are different than codex credentials use this line to\n # not forward the authorization.\n proxy_set_header Authorization \"\";\n}\n```\n\nSpecify a reverse proxy sub path (if you have one) in `config/hypercorn.toml`\n\n```toml\nroot_path = \"/codex\"\n```\n\n#### Nginx Reverse Proxy 502 when container refreshes\n\nNginx requires a special trick to refresh dns when linked Docker containers\nrecreate. See this\n[nginx with dynamix upstreams](https://tenzer.dk/nginx-with-dynamic-upstreams/)\narticle.\n\n### Restricted Memory Environments\n\nCodex can run with as little as 1GB available RAM. Large batch jobs \u2013like\nimporting and indexing tens of thousands of comics at once\u2013 will run faster the\nmore memory is available to Codex. The biggest gains in speed happen when you\nincrease memory up to about 6GB. Codex batch jobs do get faster the more memory\nit has above 6GB, but with diminishing returns.\n\nIf you must run Codex in an admin restricted memory environment you might want\nto temporarily give Codex a lot of memory to run a very large import job and\nthen restrict it for normal operation.\n\n## <a name=\"use\">\ud83d\udcd6 Use</a>\n\n### \ud83d\udc64 Sessions & Accounts\n\nOnce your administrator has added some comic libraries, you may browse and read\ncomics. Codex will remember your preferences, bookmarks and progress in the\nbrowser session. Codex destroys anonymous sessions and bookmarks after 60 days.\nTo preserve these settings across browsers and after sessions expire, you may\nregister an account with a username and password. You will have to contact your\nadministrator to reset your password if you forget it.\n\n### \u1be4 OPDS\n\nCodex supports OPDS syndication and OPDS streaming. You may find the OPDS url in\nthe side drawer. It should take the form:\n\n`http(s)://host.tld(:9810)(/root_path)/opds/v1.2/`\n\nor\n\n`http(s)://host.tld(:9810)(/root_path)/opds/v2.0/`\n\nOPDS 2.0 support is experimental and not widely or well supported by clients.\nOPDS 2.0 book readers exist, but I am not yet aware of an OPDS 2.0 comic reader.\n\n#### Clients\n\n- iOS has [Panels](https://panels.app/), [PocketBooks](https://pocketbook.ch/),\n [KYBook 3](http://kybook-reader.com/), and\n [Chunky Comic Reader](https://apps.apple.com/us/app/chunky-comic-reader/id663567628)\n- Android has\n [Moon+](https://play.google.com/store/apps/details?id=com.flyersoft.moonreader)\n and\n [Librera](https://play.google.com/store/apps/details?id=com.foobnix.pdf.reader)\n\nKybook 3 does not seem to support http basic authentication, so Cbbodex users\nare not supported.\n\n#### HTTP Basic Authentication\n\nIf you wish to access OPDS as your Codex User. You will have to add your\nusername and password to the URL. Some OPDS clients do not asssist you with\nauthentication. In that case the OPDS url will look like:\n\n`http(s)://username:password@host.tld(:9810)(/root_path)/opds/v1.2/`\n\n#### Supported OPDS Specifications\n\n##### OPDS v1\n\n- [OPDS 1.2](https://specs.opds.io/opds-1.2.html)\n- [OPDS-PSE 1.2](https://github.com/anansi-project/opds-pse/blob/master/v1.2.md)\n- [OPDS Authentication 1.0](https://drafts.opds.io/authentication-for-opds-1.0.html)\n- [OpenSearch 1.1](https://github.com/dewitt/opensearch)\n\n##### OPDS v2\n\n- [OPDS 2.0 (draft)](https://drafts.opds.io/opds-2.0.html)\n- [OPDS 2.0 Progression (proposal)](https://github.com/opds-community/drafts/discussions/67)\n\n## <a name=\"troubleshooting\">\ud83e\ude7a Troubleshooting</a>\n\n### \ud83d\udcd2 Logs\n\nCodex collects its logs in the `config/logs` directory. Take a look to see what\nth e server is doing.\n\nYou can change how much codex logs by setting the `LOGLEVEL` environment\nvariable. By default this level is `INFO`. To see more verbose messages, run\ncodex like:\n\n```sh\nLOGLEVEL=DEBUG codex\n```\n\n### Watching Filesystem Events with Docker\n\nCodex tries to watch for filesystem events to instantly update your comic\nlibraries when they change on disk. But these native filesystem events are not\ntranslated between macOS & Windows Docker hosts and the Docker Linux container.\nIf you find that your installation is not updating to filesystem changes\ninstantly, you might try enabling polling for the affected libraries and\ndecreasing the `poll_every` value in the Admin console to a frequency that suits\nyou.\n\n### Emergency Database Repair\n\nIf the database becomes corrupt, Codex includes a facility to rebuild the\ndatabase. Place a file named `rebuild_db` in your Codex config directory like\nso:\n\n```sh\ntouch config/rebuild_db\n```\n\nShut down and restart Codex.\n\nThe next time Codex starts it will back up the existing database and try to\nrebuild it. The database lives in the config directory as the file\n`config/db.sqlite3`. If this procedure goes kablooey, you may recover the\noriginal database at `config/backups/codex.sqlite3.before-rebuild`. Codex will\nremove the `rebuild_db` file.\n\n### Warnings to Ignore\n\n#### StreamingHttpResponse Iterator Warning\n\n```pycon\npackages/django/http/response.py:517: Warning: StreamingHttpResponse must consume synchronous iterators in order to serve them asynchronously. Use an asynchronous iterator instead.\n```\n\nThis is a known warning and does not represent anything bad happening. It's an\nartifact of the Django framework slowly supporting asynchronous server endpoints\nand unfortunately isn't practical to remove yet.\n\n## <a name=\"alternatives-to-codex\">\ud83d\udcdaAlternatives</a>\n\n- [Kavita](https://www.kavitareader.com/) has light metadata filtering/editing,\n supports comics, eBooks, and features for manga.\n- [Komga](https://komga.org/) has light metadata editing.\n- [Ubooquity](https://vaemendis.net/ubooquity/) reads both comics and eBooks.\n- [Mylar](https://github.com/mylar3/mylar3) is the best comic book manager which\n also has a built in reader.\n- [Comictagger](https://github.com/comictagger/comictagger) is a comic metadata\n editor. It comes with a powerful command line and desktop GUI.\n\n## <a name=\"contributing\">\ud83e\udd1d Contributing</a>\n\n### <a name=\"bug_reports\">\ud83d\udc1b Bug Reports</a>\n\nIssues and feature requests are best filed on the\n[Github issue tracker](https://github.com/ajslater/codex/issues).\n\n### <a name=\"out-of-scope\">\ud83d\udeab Out of Scope</a>\n\n- I have no intention of making this an eBook reader.\n- I think metadata editing would be better placed in a comic manager than a\n reader.\n\n### <a name=\"develop-codex\">\ud83d\udee0 Develop</a>\n\nCodex is a Django Python webserver with a VueJS front end.\n\n`/codex/codex/` is the main django app which provides the webserver and\ndatabase.\n\n`/codex/frontend/` is where the vuejs frontend lives.\n\nMost of Codex development is now controlled through the Makefile. Type `make`\nfor a list of commands.\n\n## <a name=\"discord\">\ud83d\udcac Support</a>\n\nBy the generosity of the good people of\n[Mylar](https://github.com/mylar3/mylar3), I and other Codex users answer\nquestions on the [Mylar Discord](https://discord.gg/6UG94R7E8T). Please use the\n`#codex-support` channel to ask for help with Codex.\n\n## <a name=\"links\">\ud83d\udd17 Links</a>\n\n- [Docker Image](https://hub.docker.com/r/ajslater/codex)\n- [PyPi Package](https://pypi.org/project/codex/)\n- [GitHub Project](https://github.com/ajslater/codex/)\n\n## <a name=\"special-thanks\">\ud83d\ude4f\ud83c\udffb Special Thanks</a>\n\n- Thanks to [Aur\u00e9lien Mazurie](https://pypi.org/user/ajmazurie/) for allowing me\n to use the PyPi name 'codex'.\n- To [ProfessionalTart](https://github.com/professionaltart) for providing\n native Windows installation instructions.\n- Thanks to the good people of\n [#mylar](https://github.com/mylar3/mylar3#live-support--conversation) for\n continuous feedback and comic ecosystem education.\n\n## <a name=\"enjoy\">\ud83d\ude0a Enjoy</a>\n\n\n",
"bugtrack_url": null,
"license": "GPL-3.0-only",
"summary": "A comic archive web server.",
"version": "1.7.10",
"project_urls": {
"Docker Image": "https://hub.docker.com/r/ajslater/codex",
"Documentation": "https://github.com/ajslater/codex",
"Homepage": "https://github.com/ajslater/codex",
"News": "https://github.com/ajslater/codex/blob/main/NEWS.md",
"Report Issues": "https://github.com/ajslater/codex/issues",
"Repository": "https://github.com/ajslater/codex"
},
"split_keywords": [
"comic",
" cbz",
" cbr",
" cbt",
" pdf"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2c3bc0d43def09d19d4a42fb60a62d7902255aec149f2a3946ed76894087bfdc",
"md5": "fee6991b657037288a094507f7d3ba88",
"sha256": "4f219f8eed2147ae7ded0e07177aacbcb7fa7fbacac9ffee4ac1ab2daac129a9"
},
"downloads": -1,
"filename": "codex-1.7.10-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fee6991b657037288a094507f7d3ba88",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 18878277,
"upload_time": "2024-11-19T02:05:53",
"upload_time_iso_8601": "2024-11-19T02:05:53.989320Z",
"url": "https://files.pythonhosted.org/packages/2c/3b/c0d43def09d19d4a42fb60a62d7902255aec149f2a3946ed76894087bfdc/codex-1.7.10-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ae93e9a7c1058c935fbc2112fdc076aa6f3c91436fcf0edb254e2a3e67cc645a",
"md5": "8807a7bd33a7a915e34536eb21e8ed35",
"sha256": "152fb6d436f2ef9349cb82c9b6df9d9e7f65f53cdea873b89e63debcb7e2e696"
},
"downloads": -1,
"filename": "codex-1.7.10.tar.gz",
"has_sig": false,
"md5_digest": "8807a7bd33a7a915e34536eb21e8ed35",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 18653138,
"upload_time": "2024-11-19T02:05:56",
"upload_time_iso_8601": "2024-11-19T02:05:56.712554Z",
"url": "https://files.pythonhosted.org/packages/ae/93/e9a7c1058c935fbc2112fdc076aa6f3c91436fcf0edb254e2a3e67cc645a/codex-1.7.10.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-19 02:05:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ajslater",
"github_project": "codex",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"circle": true,
"lcname": "codex"
}
JSON
