Isekai Core

Isekai Core is an open-source, self-hosted workspace for managing artwork and artist workflows on DeviantArt. It brings an account's artwork catalog, publishing rules, galleries, commercial queues, and reusable metadata into one application. Optional ComfyUI generation feeds the same catalog as manual uploads.

What you can do

Area	Capabilities
Artwork workspace	Upload images and videos; review, curate, and edit drafts; apply bulk metadata changes; schedule, reschedule, or publish; recover discarded drafts from Trash.
Automations	Select drafts using FIFO, LIFO, or random ordering; apply metadata defaults; configure fixed times, intervals, or daily quotas; inspect test previews and execution logs.
Commercial queues	Prepare exclusive listings with price presets and subscription posts with target tiers; track browser jobs, retry failures, and test subscription actions with dry runs.
Galleries	Browse DeviantArt galleries and their contents; create, edit, delete, and reorder folders.
Templates and pricing	Reuse tags and descriptions across artwork; save fixed prices or price ranges for exclusive listings.
Generation	Connect ComfyUI servers, save workflow recipes, trigger manual or inventory/scheduled runs, and inspect their results.
Accounts and administration	Sign in through DeviantArt OAuth, manage integration API keys, inspect authorization health, and administer team access and instance settings.
Dashboard	See review and draft inventory, publication activity, failures, commercial queue status, enabled automations, and active generation runs.

Commercial website actions use the separate Isekai Chrome Extension. Generation uses a ComfyUI server with Isekai Comfy Node installed. Neither integration is required to manage manually uploaded artwork or galleries.

How it works

The React frontend calls an Express API. PostgreSQL stores artwork, account, template, automation, and run records; S3-compatible storage holds original media and thumbnails. Redis/BullMQ carries background jobs to the publisher and a separate media worker.

Different actions take different paths:

• Catalog and template edits update records through the API.
• Gallery operations call DeviantArt directly through the API.
• Publishing, generation dispatch, and maintenance run in the publisher process.
• Subscription and exclusive jobs live in PostgreSQL and are claimed through the API by the Chrome extension.
• ComfyUI executes models externally and uploads results into Core's Review or Draft workspace.

See Architecture for editable Mermaid capability and runtime diagrams, execution paths, and source references.

Run with Docker

You need Docker with Compose and a DeviantArt OAuth application. Both Compose configurations include PostgreSQL, Redis, and MinIO; an external storage account is optional.

git clone https://github.com/isekai-sh/isekai-core.git
cd isekai-core
cp .env.example .env

Edit .env before starting:

• Set DEVIANTART_CLIENT_ID and DEVIANTART_CLIENT_SECRET. Register http://localhost:4000/api/auth/deviantart/callback as the local OAuth redirect URI.
• Replace SESSION_SECRET and ENCRYPTION_KEY with independently generated values. Use openssl rand -base64 32 for the session secret and openssl rand -hex 32 for the encryption key.
• For local HTTP, set COOKIE_SECURE=false. Use true with HTTPS.
• Keep the bundled MinIO settings for local use. S3_ENDPOINT is the server-facing address; S3_PRESIGNED_ENDPOINT and S3_PUBLIC_URL must be reachable by the browser.

Choose the configuration that matches what you want to run:

Configuration	Command	Contents
Pinned release images	docker compose -f docker-compose.prod.yml up -d	API, frontend, publisher, separate media worker, and data services.
Build this checkout	docker compose up --build -d	API, frontend, publisher, and data services. This file does not include the separate media worker.

The release configuration uses pinned image digests and does not build your checkout. Its backend applies the migrations bundled in that image at startup. The source-build backend also applies migrations at startup. For source development with thumbnail processing, use the separate media-worker command below.

Default local endpoints:

Service	Address
Application	localhost:3000
API health	localhost:4000/api/health
Publisher readiness	localhost:8000/ready
MinIO console	localhost:9001

The first successful sign-in becomes the instance administrator. Team onboarding is controlled in Settings. For a remote deployment, configure externally reachable frontend, API, OAuth callback, and storage URLs; replace the bundled development database/storage credentials before exposing the services.

Use the same Compose file for lifecycle commands:

docker compose -f docker-compose.prod.yml logs -f backend publisher media-worker
docker compose -f docker-compose.prod.yml down

Develop locally

Use Node.js 22.12+ within the 22.x release line, or Node.js 24+, and pnpm 9+. The current Prisma dependency also supports Node.js 20.19+, which is more specific than the root manifest's Node 20 minimum.

Start from the root .env copied above. For application processes running on your host, change these values:

DATABASE_URL=postgresql://isekai:isekai@localhost:5433/isekai
REDIS_URL=redis://localhost:6379
S3_ENDPOINT=http://localhost:9000
S3_PRESIGNED_ENDPOINT=http://localhost:9000
S3_PUBLIC_URL=http://localhost:9000/isekai-uploads
NODE_ENV=development
COOKIE_SECURE=false
VITE_API_URL=http://localhost:4000

The development Vite proxy preserves /api, so its target is the API origin without an /api suffix. The Docker frontend's VITE_API_URL instead includes /api, as shown in .env.example.

Run these commands from the repository root:

docker compose up -d postgres redis minio minio-init

# Prisma CLI runs from packages/shared; give it the host database URL explicitly.
export DATABASE_URL=postgresql://isekai:isekai@localhost:5433/isekai
pnpm install
pnpm db:generate
pnpm db:migrate
pnpm --filter @isekai/shared build
pnpm dev

pnpm dev starts the frontend, API, publisher, and shared-package watcher. In another terminal, start the media worker with the same root configuration:

DOTENV_CONFIG_PATH=../../.env pnpm --filter isekai-publisher exec tsx watch src/media-worker.ts

The relative dotenv path is resolved from the publisher package's working directory. The media worker exposes health/readiness on port 8001. It is separate from pnpm dev; without it, image uploads can queue thumbnails but those jobs will not be processed by the publisher.

Useful commands:

Command	Purpose
pnpm dev:frontend, pnpm dev:backend, pnpm dev:publisher	Start an individual application.
pnpm build	Build the shared package and applications.
pnpm db:generate	Generate the Prisma client.
pnpm db:migrate	Run Prisma development migrations.
pnpm db:studio	Inspect the configured database with Prisma Studio.
pnpm test	Run package test scripts; the frontend script currently skips tests.
pnpm --filter isekai-frontend exec vitest run	Run the frontend tests explicitly.
pnpm lint	Run repository ESLint checks.
pnpm format:check	Check formatting.

Keep the database URL exported when running Prisma CLI commands. Use a development database for db:migrate; deployed environments use prisma migrate deploy with their release's migrations.

Repository map

apps/
  isekai-frontend/    React, Vite, TanStack Query, Zustand, Tailwind
  isekai-backend/     Express API, authentication, domain routes, job producers
  isekai-publisher/   Publisher/schedulers and separate media-worker entry point
packages/shared/     Prisma schema/client, types, storage, publishing and token logic
docs/                Architecture and Mermaid diagrams
.context/            Implementation notes and contributor workflows

packages/shared is imported by the applications; it is not a separate service. The Prisma schema and application scripts describe the current data model and commands. Some .context notes describe older releases; use the current architecture and source when they differ.

Contributing and support

Read CONTRIBUTING.md and LINTING.md, and run the checks relevant to your change. Report bugs or ask questions through GitHub Issues.

Isekai Core is licensed under AGPL-3.0.