codex


Namecodex JSON
Version 1.1.3 PyPI version JSON
download
home_pagehttps://github.com/ajslater/codex
SummaryA comic archive web server.
upload_time2023-01-25 02:52:47
maintainer
docs_urlNone
authorAJ Slater
requires_python>=3.9,<4.0
licenseGPL-2.0-only
keywords comic cbz cbr cbt pdf
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # 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.
- 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, streaming, search and authentication.

### 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://codex.sl8r.net/) 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 as a Native Application

You can also run Codex as a natively installed python application with pip.

#### Wheel Build Dependencies

You'll need to install these system dependencies before installing Codex.

##### macOS

```sh
brew install jpeg libffi libyaml libzip openssl poppler python unrar webp
```

##### Linux

###### <a href="#debian">Debian</a>

Like Ubuntu, Mint, MX and others.

```sh
apt install build-essential libffi-dev libjpeg-dev libssl-dev libwebp7 poppler-utils python3-pip zlib1g-dev
```

older releases may use the `libweb6` package instead.

###### Debian on ARM

The python cryptography wheel needs compiling on rare architectures. Install the
Rust compiler.

```sh
apt install cargo
```

###### Alpine

```sh
apk add bsd-compat-headers build-base jpeg-dev libffi-dev libwebp openssl-dev poppler-utils yaml-dev zlib-dev
```

##### Install unrar Runtime Dependency on 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

#### Windows

Windows users should use Docker to run Codex until this documentation section is
complete.

Codex can _probably_ run using Cygwin or the Windows Linux Subsystem but I
haven't done it yet. Contributions to this documentation accepted on
[the outstanding issue](https://github.com/ajslater/codex/issues/76) or discord.

##### Windows Linux Subsystem

Untested. Try following the instructions for [Debian](#debian) above.

##### Cygwin

Untested partial instructions for the brave.

1. Install [Cygwin](https://www.cygwin.com/).
2. Install wget with cygwin.
3. Install:
   - python3.9+
   - gcc
   - gcc-g++
   - libffi-devel
   - libjpeg-devel
   - libssl-devel
   - mpfr
   - mpc
   - python3-devel
   - python39-cffi
   - python3.9-openssl with cygwin.
4. Using a terminal:

```sh
pip install wheel
```

#### Install Codex with pip

You may now install Codex with pip

```sh
pip3 install codex
```

#### Run Codex Natively

pip should install the codex binary on your path. Run

```sh
codex
```

and then 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 path to config>/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.

### PDFs

Codex 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`

## <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"
max_db_ops = 100000

```

The config directory also holds the main sqlite database, the Whoosh search
index, a Django cache and comic book cover thumbnails.

### Environment Variables

- `LOGLEVEL` will change how verbose codex's logging is. Valid values are
  `ERROR`, `WARNING`, `INFO`, `VERBOSE`, `DEBUG`. The default is `INFO`.
- `TIMEZONE` or `TZ` will 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_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.
- `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.

### 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"

    # This example uses a docker container named 'codex' at sub-path /codex
    # Use a valid IP or resolvable host name for other configurations.
    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.

## <a name="usage">πŸ“– Usage</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/`

#### Clients

- iOS has [Panels](https://panels.app/), [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)

#### 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 1.2
- OPDS-PSE 1.1
- OPDS Authentication 1.0
- OpenSearch

## <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 messages run codex like:

```bash
LOGLEVEL=VERBOSE codex
```

To see a great deal of noisy messages from dependencies try:

```bash
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 facitlity 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/db.sqlite3.backup`.

### Bulk Database Updates Fail

I've tested Codex's bulk database updater to batch 100,000 filesystem events at
a time. With enough RAM Codex could probably batch much more. But if you find
that updating large batches of comics are failing, consider setting a the
`max_db_ops` value in `hypercorn.toml` to a lower value. 1000 will probably
still be pretty fast, for instance.

### πŸ› Bug Reports

Issues and feature requests are best filed on the
[Github issue tracker](https://github.com/ajslater/codex/issues).

By the generosity of the good people of
[Mylar](https://github.com/mylar3/mylar3), I and other Codex users may be found
answering questions on the [Mylar Discord](https://discord.gg/6UG94R7E8T).
Please use the `#codex-support` channel to ask for help with Codex.

## <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="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="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.

`/codex/dev-env-setup.sh` will install development dependencies.

`/codex/dev-ttabs.sh` will run the three or four different servers recommended
for development in terminal tabs.

`/codex/dev-codex.sh` runs the main Django server. Set the `DEBUG` environment
variable to activate debug mode: `DEBUG=1 ./run.sh`. This also lets you run the
server without collecting static files for production and with a hot reloading
frontend. I recommend setting `LOGLEVEL=VERBOSE` for development as well.

`/codex/frontend/dev-server.sh` runs the development autoreloading frontend with
vite.

### Links

- [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'.
- 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>

![These simple people have managed to tap into the spiritual forces that mystics and yogis spend literal lifetimes seeking. I feel... ...I feel...](strange.jpg)

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/ajslater/codex",
    "name": "codex",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.9,<4.0",
    "maintainer_email": "",
    "keywords": "comic,cbz,cbr,cbt,pdf",
    "author": "AJ Slater",
    "author_email": "aj@slater.net",
    "download_url": "https://files.pythonhosted.org/packages/80/db/eda2004bf5ea5fdd165997a0bdba5dcd744e61a946c7417e8f167a8c380c/codex-1.1.3.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- 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.\n- Read comics in a variety of aspect ratios that fit your screen.\n- Per user bookmarking. Per browser bookmarks even before you make an account.\n- Watches the filesystem and automatically imports new or changed comics.\n- Private Libraries accessible only to certain groups of users.\n- Reads CBZ, CBR, CBT, and PDF formatted comics.\n- Syndication with OPDS, streaming, search and authentication.\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://codex.sl8r.net/) to get a feel for\nCodex.\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 as a Native Application\n\nYou can also run Codex as a natively installed python application with pip.\n\n#### Wheel Build Dependencies\n\nYou'll need to install these system dependencies before installing Codex.\n\n##### macOS\n\n```sh\nbrew install jpeg libffi libyaml libzip openssl poppler python unrar webp\n```\n\n##### Linux\n\n###### <a href=\"#debian\">Debian</a>\n\nLike Ubuntu, Mint, MX and others.\n\n```sh\napt install build-essential libffi-dev libjpeg-dev libssl-dev libwebp7 poppler-utils python3-pip zlib1g-dev\n```\n\nolder releases may use the `libweb6` package instead.\n\n###### Debian on ARM\n\nThe python cryptography wheel needs compiling on rare architectures. Install the\nRust compiler.\n\n```sh\napt install cargo\n```\n\n###### Alpine\n\n```sh\napk add bsd-compat-headers build-base jpeg-dev libffi-dev libwebp openssl-dev poppler-utils yaml-dev zlib-dev\n```\n\n##### Install unrar Runtime Dependency on 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#### Windows\n\nWindows users should use Docker to run Codex until this documentation section is\ncomplete.\n\nCodex can _probably_ run using Cygwin or the Windows Linux Subsystem but I\nhaven't done it yet. Contributions to this documentation accepted on\n[the outstanding issue](https://github.com/ajslater/codex/issues/76) or discord.\n\n##### Windows Linux Subsystem\n\nUntested. Try following the instructions for [Debian](#debian) above.\n\n##### Cygwin\n\nUntested partial instructions for the brave.\n\n1. Install [Cygwin](https://www.cygwin.com/).\n2. Install wget with cygwin.\n3. Install:\n   - python3.9+\n   - gcc\n   - gcc-g++\n   - libffi-devel\n   - libjpeg-devel\n   - libssl-devel\n   - mpfr\n   - mpc\n   - python3-devel\n   - python39-cffi\n   - python3.9-openssl with cygwin.\n4. Using a terminal:\n\n```sh\npip install wheel\n```\n\n#### Install Codex with pip\n\nYou may now install Codex with pip\n\n```sh\npip3 install codex\n```\n\n#### Run Codex Natively\n\npip should install the codex binary on your path. Run\n\n```sh\ncodex\n```\n\nand then 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 path to config>/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### PDFs\n\nCodex only reads PDF metadata from the filename. If you decide to include PDFs\nin your comic library, I recommend taking time to rename your files so Codex can\nfind some metadata. Codex recognizes several file naming schemes. This one has\ngood results:\n\n`{series} v{volume} #{issue} {title} ({year}) {ignored}.pdf`\n\n## <a name=\"configuration\">\u2699\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\"\nmax_db_ops = 100000\n\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- `LOGLEVEL` will change how verbose codex's logging is. Valid values are\n  `ERROR`, `WARNING`, `INFO`, `VERBOSE`, `DEBUG`. The default is `INFO`.\n- `TIMEZONE` or `TZ` will explicitly 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_SKIP_INTEGRITY_CHECK=1` will skip the database integrity repair that\n  runs when codex starts.\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### 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\n    proxy_set_header  Host              $http_host;\n    proxy_set_header  X-Forwarded-For   $proxy_add_x_forwarded_for;\n    proxy_set_header  X-Forwarded-Host  $server_name;\n    proxy_set_header  X-Forwarded-Port  $server_port;\n    proxy_set_header  X-Forwarded-Proto $scheme;\n    proxy_set_header  X-Real-IP         $remote_addr;\n    proxy_set_header  X-Scheme          $scheme;\n\n    # Websockets\n    proxy_http_version 1.1;\n    proxy_set_header Upgrade $http_upgrade;\n    proxy_set_header Connection \"Upgrade\"\n\n    # This example uses a docker container named 'codex' at sub-path /codex\n    # Use a valid IP or resolvable host name for other configurations.\n    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\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## <a name=\"usage\">\ud83d\udcd6 Usage</a>\n\n### 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\n#### Clients\n\n- iOS has [Panels](https://panels.app/), [KYBook 3](http://kybook-reader.com/),\n  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\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 1.2\n- OPDS-PSE 1.1\n- OPDS Authentication 1.0\n- OpenSearch\n\n## <a name=\"troubleshooting\">\ud83e\ude7a Troubleshooting</a>\n\n### 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 messages run codex like:\n\n```bash\nLOGLEVEL=VERBOSE codex\n```\n\nTo see a great deal of noisy messages from dependencies try:\n\n```bash\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 facitlity to rebuild the\ndatabase. Place a file named `rebuild_db` in your Codex config directory like\nso:\n\n```sh\n  touch 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/db.sqlite3.backup`.\n\n### Bulk Database Updates Fail\n\nI've tested Codex's bulk database updater to batch 100,000 filesystem events at\na time. With enough RAM Codex could probably batch much more. But if you find\nthat updating large batches of comics are failing, consider setting a the\n`max_db_ops` value in `hypercorn.toml` to a lower value. 1000 will probably\nstill be pretty fast, for instance.\n\n### \ud83d\udc1b Bug Reports\n\nIssues and feature requests are best filed on the\n[Github issue tracker](https://github.com/ajslater/codex/issues).\n\nBy the generosity of the good people of\n[Mylar](https://github.com/mylar3/mylar3), I and other Codex users may be found\nanswering questions on the [Mylar Discord](https://discord.gg/6UG94R7E8T).\nPlease use the `#codex-support` channel to ask for help with Codex.\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=\"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=\"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\n`/codex/dev-env-setup.sh` will install development dependencies.\n\n`/codex/dev-ttabs.sh` will run the three or four different servers recommended\nfor development in terminal tabs.\n\n`/codex/dev-codex.sh` runs the main Django server. Set the `DEBUG` environment\nvariable to activate debug mode: `DEBUG=1 ./run.sh`. This also lets you run the\nserver without collecting static files for production and with a hot reloading\nfrontend. I recommend setting `LOGLEVEL=VERBOSE` for development as well.\n\n`/codex/frontend/dev-server.sh` runs the development autoreloading frontend with\nvite.\n\n### Links\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- 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![These simple people have managed to tap into the spiritual forces that mystics and yogis spend literal lifetimes seeking. I feel... ...I feel...](strange.jpg)\n",
    "bugtrack_url": null,
    "license": "GPL-2.0-only",
    "summary": "A comic archive web server.",
    "version": "1.1.3",
    "split_keywords": [
        "comic",
        "cbz",
        "cbr",
        "cbt",
        "pdf"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "f02a9d8f7535bc399146bde449fb9484ec1031bd489dccd63c197561c1a544fb",
                "md5": "8d1f3bd92e5666201715b990dad80f9b",
                "sha256": "5332f0ac16ba81bbd794b69ad5633423a6552eb19563ab128305454fbf890e7a"
            },
            "downloads": -1,
            "filename": "codex-1.1.3-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "8d1f3bd92e5666201715b990dad80f9b",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.9,<4.0",
            "size": 15948407,
            "upload_time": "2023-01-25T02:52:44",
            "upload_time_iso_8601": "2023-01-25T02:52:44.374553Z",
            "url": "https://files.pythonhosted.org/packages/f0/2a/9d8f7535bc399146bde449fb9484ec1031bd489dccd63c197561c1a544fb/codex-1.1.3-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "80dbeda2004bf5ea5fdd165997a0bdba5dcd744e61a946c7417e8f167a8c380c",
                "md5": "e49325d0211c175be4e30037c75da111",
                "sha256": "0ffaa168007834a315f9a7c7d65995d1e187b1130465d938cd64fdc34b3ed64e"
            },
            "downloads": -1,
            "filename": "codex-1.1.3.tar.gz",
            "has_sig": false,
            "md5_digest": "e49325d0211c175be4e30037c75da111",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.9,<4.0",
            "size": 15875691,
            "upload_time": "2023-01-25T02:52:47",
            "upload_time_iso_8601": "2023-01-25T02:52:47.192748Z",
            "url": "https://files.pythonhosted.org/packages/80/db/eda2004bf5ea5fdd165997a0bdba5dcd744e61a946c7417e8f167a8c380c/codex-1.1.3.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2023-01-25 02:52:47",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "github_user": "ajslater",
    "github_project": "codex",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "circle": true,
    "lcname": "codex"
}
        
Elapsed time: 0.10851s