Run Locally

You don’t need a VPS to run Isekai Core if you prefer local installation. You can run the full application on your personal computer (Windows, macOS, or Linux) using Docker Desktop and Isekai Core will function entirely offline (except when publishing to DeviantArt).

This is the recommended method for:

• Testing the application before deploying
• Personal usage
• Developing custom integrations

Tip

Zero Configuration Storage: Isekai now includes MinIO for S3-compatible storage out of the box. No external storage account needed for local development!

Prerequisites

• Docker Desktop: Download and install Docker Desktop for your Operating System
• DeviantArt Application

Installation Steps

1. Set up your directory

   Open your terminal (PowerShell, Command Prompt, or Terminal) and create a folder for the project:

   # Create a folder
   mkdir isekai
   cd isekai
   
   # Download the Docker Compose file
   curl -o docker-compose.yml https://raw.githubusercontent.com/isekai-sh/isekai-core/main/docker-compose.yml
   
   # Download the env example
   curl -o .env https://raw.githubusercontent.com/isekai-sh/isekai-core/main/.env.example

   Note: On Windows PowerShell, you might need to use Invoke-WebRequest or just download the files manually from the browser.

2. Configure your Environment Variables

   Open the .env file in a text editor (Notepad, TextEdit, VS Code) and edit frontend and backend URLs:

   NODE_ENV=production
   PORT=4000
   
   # Frontend accesses Backend here
   VITE_API_URL=http://localhost:4000/api
   
   # Browser accesses Frontend here
   FRONTEND_URL=http://localhost:3000

   Edit your DeviantArt Application credentials:

   DEVIANTART_CLIENT_ID=12345
   DEVIANTART_CLIENT_SECRET=your-secret
   DEVIANTART_REDIRECT_URI=http://localhost:4000/api/auth/deviantart/callback

   Generate strong random strings for session management and encryption. You can use a password generator or run openssl rand -hex 32 in a terminal.

   SESSION_SECRET=long_random_string_here
   ENCRYPTION_KEY=32_byte_hex_string_here

   Note

   Storage is pre-configured! The default .env includes MinIO settings that work out of the box. You don’t need to configure any external storage for local development.

3. Run The Container

   Start the application stack:

   docker compose up -d

   Docker will build the images locally (Frontend, Backend, Publisher) and start all services (MinIO, Postgres, Redis). This might take a few minutes the first time.

   Note

   The docker-compose.yml builds images locally from source. If you prefer to use pre-built images from GitHub Container Registry, use docker-compose.prod.yml instead:

   docker compose -f docker-compose.prod.yml up -d

4. Access the app

   • Open your browser to http://localhost:3000
   • You should see the login screen
   • Click “Login with DeviantArt”

   Optional: Access the MinIO Console at http://localhost:9001 (login: minioadmin / minioadmin) to view uploaded files.

Managing the App

Stopping the App

To stop the app and free up system resources:

docker compose down

Updating

To update to the latest version of Isekai Core:

# If using local builds (default docker-compose.yml)
git pull  # If you cloned the repo
docker compose build --pull
docker compose up -d

# If using pre-built images (docker-compose.prod.yml)
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d

Where is my data?

By default, Docker stores data in “volumes” managed by Docker Desktop:

• postgres_data: Database with all your drafts, schedules, and settings
• redis_data: Session data and job queues
• minio_data: Uploaded images and files

Your data persists even if you restart your computer or stop the containers.

Using External Storage

If you prefer to use an external S3-compatible storage provider (Cloudflare R2, AWS S3, etc.) instead of local MinIO, see the Storage Setup guide for configuration instructions.