search

diogovalentte / mantium

Mantium is a self-hosted cross-site manga tracker. It can track manga from source sites like Manga Plus, Mangadex and ComicK.
https://ko-fi.com/diogovalentte
Other
45 stars 1 forks source link

readme

Mantium

Mantium is a cross-site manga tracker, which means that you can track manga from multiple source sites, like Mangadex and ComicK. Mantium doesn't download the chapter images; it downloads the manga metadata (name, URL, cover, etc.) and chapter metadata (number, name, URL) from the source site and shows them in a dashboard and iFrame to put in your dashboard service.

The basic workflow is:

  1. You find an interesting manga on a site.
  2. Add the manga to Mantium. Set its status (reading, dropped, etc.), and (optionally) the last chapter you read from the list of the manga's released chapters.
  3. You also configure Mantium to periodically check for new chapters (like every 30 minutes) in your mangas and notify you when they are released.
  4. After being notified that a new chapter has been released, you read it and set it in Mantium that you read the last released chapter.
  5. That's how you track a manga in Mantium.

ko-fi

Dashboard

By default, the dashboard shows the mangas with unread chapters first, ordering by the last released chapter. Unread manga names have an animation effect that changes the name color to catch your attention.

You can add a manga to Mantium using the manga URL or by searching it by name in Mantium:

Using the Manga URL Searching by Name

Sidebar

iFrame

Mantium also has an endpoint that returns an iFrame. It's a minimalist version of the dashboard, showing only mangas with unread chapters with status reading or completed. You can add it to a dashboard, for example. More about the iframe here.

image

Multimanga

A Multimanga is like a container for multiple mangas. When you add a manga to Mantium, it creates a multimanga and adds the manga to the multimanga. You actually never interact with the manga, only the multimanga. But why?

The multimanga feature solves the issue of when you want to track the same manga in multiple source sites so that you are notified whenever a new chapter is released as soon as possible in whatever source. You could add the same manga for each source, but they would act as completely different mangas. Each one would appear on a card in the dashboard/iframe, you would need to set the last read chapter for each of them and be notified of new chapters from each of them.

The multimanga feature solves this issue. With it, you add the same manga from multiple sources to the same multimanga and interact only with the multimanga. No multiple notifications or setting the last read chapter for all of them, you just set the multimanga last read chapter, and only one card will appear in the dashboard/iframe!

Current manga

A multimanga always has a manga called current manga, which is one of the multimanga's mangas. The dashboard/iframe shows the current manga's name, cover image, and last released chapter. When you select the last read chapter, the list of the current manga chapters is shown. When you're notified of a new chapter, the newest chapter of the current manga is sent in the notification.

Based on the mangas' last released chapter, Mantium tries to set the current manga to the manga with the newest released chapter by using the following rules. Take for example a multimanga with two mangas, Mantium will compare the mangas' last released chapter this way:

  1. If the chapters' numbers are equal, Mantium sets the manga that released the chapter last as the current manga.
  2. If they're not equal, Mantium will pick the manga with the biggest chapter number.
  3. Depending on the manga and source, the chapter's number can not be a number at all. When one of the manga's chapter numbers is not a number, Mantium will pick the manga that released the chapter last as the current manga.

Mantium decides which manga should be the current manga whenever you add/remove a manga from a multimanga and in the periodic job that updates the mangas in the background.

The images below show the popup that appears when you click the "Highlight" button of one of the mangas in the dashboard. It shows a form to delete the multimanga, update its status, last read chapter, and cover image, add mangas to the multimanga by searching by name or using an URL, and manage the multimanga's mangas.

Edit Multimanga Edit Multimanga Cover Image Manage Multimanga Mangas

Custom Manga

Mantium allows you to add mangas, manhwa, light novels, etc. that aren't from one of the supported source sites. You must manually track these manga, providing info about them like name, URL, cover image, etc. You can also provide the next chapter you should read from the manga, and update it every time you read a chapter.

When you read the last available chapter from a custom manga, check the "No more chapters available" checkbox so the manga is considered read instead of unread.

image

Check manga updates and notify

Mantium can periodically get the metadata of the mangas you're tracking from their source sites (like every 30 minutes). If the manga metadata (like the cover image, name, or last release chapter) changes from the currently stored metadata, Mantium updates it.

You can also set Mantium to notify you when a manga with the status "reading" or "completed" has a newly released chapter.

Integrations

Mantium has integrations, like:

More about the integrations here.

Running

By default, the API will be available on port 8080 and the dashboard on port 8501, and they're not accessible by other machines. To access the API and dashboard in other machines, you run the containers in host network mode or behind a reverse proxy.

Docker Compose

  1. There is a docker-compose.yml file in this repository. You can clone this repository to use this file or create one yourself.
  2. Create a .env file, it should be like the .env.example file and be in the same directory as the docker-compose.yml file.
  3. Start the containers:
docker compose up -d

Running manually/setting development environment

The steps are at the bottom of this README.

Notes:

iFrame usage

The Mantium API has the endpoint /v1/mangas/iframe that returns an iFrame. When you add an iFrame to your dashboard, it's >your< web browser that fetches the iFrame from the API and shows it to you, not your dashboard service running on your server. So your browser needs to be able to access the Mantium API.

The iFrame has the following arguments:

Example: https://mantium-api.domain.com/v1/mangas/iframe?api_url=http://mantium-api.domain.com&theme=dark&limit=5&showBackgroundErrorWarning=false

Mantium doesn't have any authentication system

The dashboard and the API don't have any authentication system, so anyone who can access the dashboard or the API can do whatever they want. You can add an authentication portal like Authelia or Authentik in front of the dashboard to protect it and don't expose the API at all.

API

The API docs are under the path /v1/swagger/index.html.

Manga Plus source

Only the first and last chapters are available on the Manga Plus site, so most chapters do not show on Mantium. I recommend reading the manga in the other source sites and when you get to the last chapter, remove the manga and add it again from the Manga Plus source.

Manga Updates source

The Manga Updates source is very different from the other sources:

Source site down

Sometimes the source sites can be down for some time, like in maintenance. In these cases, there is nothing Mantium can do about it, and all interactions with manga from these source sites will fail.

What to do when a manga is removed from the source site or its URL changes

If a manga is removed from the source site (like Mangedex) or its URL changes, the API will not be able to track it, as it saves the manga URL on the database when you add the manga in the dashboard and continues to use this URL forever. If this happens, the dashboard/API logs will show an error like this:

{"message":"(comick.io) Error while getting manga with URL 'https://comick.io/comic/witch-hat-atelier' chapters from source: Error while getting chapters metadata: Error while making 'GET' request: Non-200 status code -\u003e (404). Body: {\"statusCode\":404,\"message\":\"Not Found\"}"}

To fix this, delete the manga and add it again from another source site or use its new URL.

Source site URL changes

Sometimes the URL of a source site changes (like comick.fun to comick.io). In this case, please open an issue if a new release with the updated URL is not released yet.

Running manually

Database

  1. Create a docker-compose.yml file with the database service (Docker and Docker Compose are required):
services:
  mantium-db:
    container_name: mantium-db
    image: postgres:16-alpine
    volumes:
      - ./data/postgres-vol:/var/lib/postgresql/data
    environment:
      - POSTGRES_PORT=5432
      - POSTGRES_DB=postgres
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres
    ports:
      - 5432:5432
    restart: unless-stopped
  1. Start the database container:
docker compose up -d

API

  1. Export the API environment variables. The variables below are the only ones necessary to run the API, but more can be found in the .env.example file.
export POSTGRES_HOST=http://localhost
export POSTGRES_PORT=5432
export POSTGRES_DB=postgres
export POSTGRES_USER=postgres
export POSTGRES_PASSWORD=postgres
export API_PORT=8080
  1. Inside the api/ folder, install the API dependencies:
go mod download
  1. Start the API:
go run main.go

Dashboard

  1. The dashboard expects to connect to the API on the address http://localhost:8080. If the API is running in a different address, export the API address environment variable:
export API_ADDRESS=http://localhost:8081
  1. Inside the dashboard/ folder, install the dashboard dependencies:
pip install -r requirements.txt

  1. Currently, there is an issue with one of the dashboard dependencies, refer to this guide explaining more about it.

  2. Start the dashboard:

streamlit run 01_📖_Dashboard.py
  1. Access the dashboard on http://localhost:8501