Package: codex
CodexA comic archive browser and reader.✨ FeaturesCodex is a web server.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.Read comics in a variety of aspect ratios that fit your screen.Per user bookmarking. Per browser bookmarks even before you make an account.Watches the filesystem and automatically imports new or changed comics.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.Runs in 1GB of RAM, faster with more.ExamplesFilter byStory Arc and Unread,Order byPublish Date to create an event
reading list.Filter byUnread andOrder byAdded Time to see your latest unread comics.Search byyour favorite character to find their appearances across different
comics.👀 DemonstrationYou may browse alive demo serverto get a feel for
Codex.📜 NewsCodex has aNEWS fileto summarize changes that affect
users.📦 InstallationInstall & Run with DockerRun the officialDocker 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 theAdministrationsection of this
document.Install & Run as a Native ApplicationYou can also run Codex as a natively installed python application with pip.Wheel Build DependenciesYou'll need to install these system dependencies before installing Codex.macOSbrewinstalljpeglibffilibyamllibzipopensslpythonunrarwebpLinuxDebianLike Ubuntu, Mint, MX and others.aptinstallbuild-essentiallibffi-devlibjpeg-devlibssl-devlibwebp7python3-pipzlib1g-devolder releases may use thelibweb6package instead.Debian on ARMThe python cryptography wheel needs compiling on rare architectures. Install the
Rust compiler.aptinstallcargoAlpineapkaddbsd-compat-headersbuild-basejpeg-devlibffi-devlibwebpopenssl-devyaml-devzlib-devInstall unrar Runtime Dependency on LinuxCodex 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 LinuxUnrar as packaged for Alpine Linux v3.14 seems to work on Alpine v3.15WindowsWindows users should use Docker to run Codex until this documentation section is
complete.Codex canprobablyWindows Linux Subsystem but I haven't done personally
tested it yet. Try following the instructions forDebianabove. There
may be outstanding platform related bugs.Contributions to this documentation accepted onthe outstanding issueor discord.Install Codex with pipYou may now install Codex with pippip3installcodexRun Codex Nativelypip should install the codex binary on your path. Runcodexand then navigate tohttp://localhost:9810/👑 AdministrationNavigate to the Admin PanelClick 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 passwordThe 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 LibrariesThe 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 PanelAdd a Library with the "+ LIBRARY" button in the upper left.Reset the admin passwordIf you forget all your superuser passwords, you may restore the original default
admin account by running codex with theCODEX_RESET_ADMINenvironment variable
set.CODEX_RESET_ADMIN=1codexor, if using Docker:dockerrun-eCODEX_RESET_ADMIN=1-vhost-parent-dir/config:/configajslater/codexPrivate LibrariesIn the Admin Panel you may configure private libraries that are only accessible
to specific groups.A library withnogroups is accessible to every user including anonymous
users.A library withanygroups 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.PDFsCodex only reads PDF metadata from the filename. 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🎛️ ConfigurationConfig DirThe default config directory isconfig/directly under the working directory
you run codex from. You may specify an alternate config directory with the
environment variableCODEX_CONFIG_DIR.The config directory contains a file namedhypercorn.tomlwhere you can
specify ports and bind addresses. If nohypercorn.tomlis 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.Environment VariablesLOGLEVELwill change how verbose codex's logging is. Valid values areERROR,WARNING,INFO,DEBUG. The default isINFO.TIMEZONEorTZwill explicitly 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_DIRwill set the path to codex config directory. Defaults to$CWD/configCODEX_RESET_ADMIN=1will reset the admin user and its password to defaults
when codex starts.CODEX_SKIP_INTEGRITY_CHECK=1will skip the database integrity repair that
runs when codex starts.CODEX_LOG_DIRsets a custom directory for saving logfiles. Defaults to$CODEX_CONFIG_DIR/logsCODEX_LOG_TO_FILE=0will not log to files.CODEX_LOG_TO_CONSOLE=0will not log to the console.Reverse Proxynginxis often used as a TLS terminator and subpath proxy.Here's an example nginx config with a subpath named '/codex'.# HTTPproxy_set_headerHost$http_host;proxy_set_headerX-Forwarded-For$proxy_add_x_forwarded_for;proxy_set_headerX-Forwarded-Host$server_name;proxy_set_headerX-Forwarded-Port$server_port;proxy_set_headerX-Forwarded-Proto$scheme;proxy_set_headerX-Real-IP$remote_addr;proxy_set_headerX-Scheme$scheme;# Websocketsproxy_http_version1.1;proxy_set_headerUpgrade$http_upgrade;proxy_set_headerConnection"Upgrade"location/codex{proxy_passhttp://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_headerAuthorization"";}Specify a reverse proxy sub path (if you have one) inconfig/hypercorn.tomlroot_path="/codex"Nginx Reverse Proxy 502 when container refreshesNginx requires a special trick to refresh dns when linked Docker containers
recreate. See thisnginx with dynamix upstreamsarticle.Restricted Memory EnvironmentsCodex 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
you give it above 6GB, but there are diminishing returns.If you run Codex in an admin restricted memory environment you might want to
temporarily give codex a lot of memory to run a very large batch job and then
restrict it for normal operation.📖 Usage👤 Sessions & AccountsOnce 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.🗝️ API with Key AccessCodex has a limited number of API endpoints available with API Key Access. The
API Key is available on the admin/stats tab.ᯤ OPDSCodex 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/orhttp(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.ClientsiOS hasPanels,KYBook 3,
andChunky Comic ReaderAndroid hasMoon+andLibreraHTTP Basic AuthenticationIf 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 SpecificationsOPDS 1.2OPDS-PSE 1.2OPDS Authentication 1.0OpenSearch 1.1🩺 Troubleshooting📒 LogsCodex collects its logs in theconfig/logsdirectory. Take a look to see what
th e server is doing.You can change how much codex logs by setting theLOGLEVELenvironment
variable. By default this level isINFO. To see more verbose messages, run
codex like:LOGLEVEL=DEBUGcodexWatching Filesystem Events with DockerCodex 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 thepoll_everyvalue in the Admin console to a frequency that suits
you.Emergency Database RepairIf the database becomes corrupt, Codex includes a facitlity to rebuild the
database. Place a file namedrebuild_dbin your Codex config directory like
so:touchconfig/rebuild_dbShut 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 fileconfig/db.sqlite3. If this procedure goes kablooey, you may recover the
original database atconfig/db.sqlite3.backup.📚AlternativesKavitahas light metadata filtering/editing,
supports comics, eBooks, and features for manga.Komgahas light metadata editing.Ubooquityreads both comics and eBooks.Mylaris the best comic book manager which
also has a built in reader.Comictaggeris a comic metadata
editor. It comes with a powerful command line and desktop GUI.🤝 Contributing🐛 Bug ReportsIssues and feature requests are best filed on theGithub issue tracker.🚫 Out of ScopeI have no intention of making this an eBook reader.I think metadata editing would be better placed in a comic manager than a
reader.🛠 DevelopCodex 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. Typemakefor a list of commands.💬 SupportBy the generosity of the good people ofMylar, I and other Codex users answer
questions on theMylar Discord. Please use the#codex-supportchannel to ask for help with Codex.🔗 LinksDocker ImagePyPi PackageGitHub Project🙏🏻 Special ThanksThanks toAurélien Mazuriefor allowing me
to use the PyPi name 'codex'.Thanks to the good people of#mylarfor
continuous feedback and comic ecosystem education.😊 Enjoy