https://github.com/isekai-sh/isekai-core
Open source DeviantArt posting management platform with scheduling, draft management, ComfyUI integration, and publishing automation.
https://github.com/isekai-sh/isekai-core
art-automation automation automation-tools deviantart deviantart-api deviantart-publishing deviantart-scheduling open-source scheduling self-hosted workflow-automation
Last synced: about 2 months ago
JSON representation
Open source DeviantArt posting management platform with scheduling, draft management, ComfyUI integration, and publishing automation.
- Host: GitHub
- URL: https://github.com/isekai-sh/isekai-core
- Owner: isekai-sh
- License: agpl-3.0
- Created: 2025-12-20T16:54:14.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-02-02T16:20:36.000Z (4 months ago)
- Last Synced: 2026-02-03T05:35:21.068Z (4 months ago)
- Topics: art-automation, automation, automation-tools, deviantart, deviantart-api, deviantart-publishing, deviantart-scheduling, open-source, scheduling, self-hosted, workflow-automation
- Language: TypeScript
- Homepage: https://isekai.sh
- Size: 3.32 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Isekai Core
[](https://github.com/isekai-sh/isekai-core/actions/workflows/ci.yml)
[](https://codecov.io/gh/isekai-sh/isekai-core)
[](https://www.gnu.org/licenses/agpl-3.0)
[](https://nodejs.org)
[](https://pnpm.io)
[](https://www.typescriptlang.org/)
> Open source DeviantArt posting management platform with scheduling, draft management, ComfyUI integration, and robust publishing automation.
Isekai is a modern web application that helps artists manage their DeviantArt posting workflow with features like scheduled publishing, draft organization, and AI image generation integration through ComfyUI.
---
## 📚 Documentation
**For comprehensive documentation, see [`.context/substrate.md`](.context/substrate.md)**
The `.context/` directory contains complete documentation following the [Substrate Methodology](https://github.com/andrefigueira/.context):
- **[Architecture](.context/architecture/overview.md)** - System design and patterns
- **[API Reference](.context/api/endpoints.md)** - All 19 route groups documented
- **[Database Schema](.context/database/schema.md)** - Complete Prisma schema
- **[Features](.context/features/)** - Automation, publishing, browse, sales
- **[Development](.context/workflows.md)** - Setup, testing, and contribution workflow
- **[Code Style](.context/ai-rules.md)** - Conventions and patterns
AI tools: See [CLAUDE.md](CLAUDE.md) for entry point.
---
## Features
- **DeviantArt Integration**: OAuth authentication and seamless posting
- **Scheduled Publishing**: Plan and automate your DeviantArt posts
- **Draft Management**: Organize and edit your artwork before publishing
- **ComfyUI Integration**: Generate and manage AI artwork -- check out [Isekai Comfy Node](https://github.com/isekai-sh/isekai-comfy-node)
- **Cloud Storage**: Cloudflare R2 for reliable file storage
## Tech Stack
### Frontend (React App)
- **Framework**: React 18 with TypeScript
- **Build Tool**: Vite 6
- **Styling**: Tailwind CSS 3
- **Routing**: React Router
- **State Management**: React Query (TanStack Query)
### Backend (API)
- **Runtime**: Node.js 20+
- **Framework**: Express.js
- **Language**: TypeScript
- **Database**: PostgreSQL 16 with Prisma ORM
- **Cache/Sessions**: Redis 7
- **Authentication**: OAuth 2.0 (DeviantArt)
- **Storage**: Cloudflare R2 (S3-compatible)
- **Job Queue**: BullMQ
### Publisher Worker (Microservice)
- **Runtime**: Node.js 20+
- **Architecture**: Dedicated background job processor
- **Queue**: BullMQ with Redis
- **Features**: Fault isolation, independent scaling, graceful shutdown
- **Monitoring**: Health check endpoints (/health, /ready, /metrics)
### Prerequisites
- Node.js 20+
- pnpm 9+
- Docker & Docker Compose
- PostgreSQL 16 (or use Docker)
- Redis 7 (or use Docker)
- Prisma CLI (installed via pnpm)
- DeviantArt Application -- register your own app at https://www.deviantart.com/developers/apps
- Cloudflare R2 credentials, free tier is enough for testing
## Quick Start
### Running Docker with pre-built image
```bash
# Clone the repository
git clone https://github.com/isekai-sh/isekai-core.git
cd isekai-core
# Copy and edit your environment variables
cp .env.example .env
# Start the Docker container
docker compose up --build
```
The application will be available at:
- Frontend (React): http://localhost:3000
- Backend (API): http://localhost:4000
- Publisher (Health): http://localhost:8000
### Building Docker image locally
```bash
# Development: build locally and run
docker-compose -f docker-compose.local.yml up --build
```
## Project Structure
```
isekai/
├── apps/
│ ├── isekai-backend/ # Express backend API (port 4000)
│ ├── isekai-frontend/ # React frontend application (port 3000)
│ └── isekai-publisher/ # DeviantArt publishing worker (microservice)
├── packages/
│ └── shared/ # Shared types and database schema
├── docker-compose.yml # Local development services
└── pnpm-workspace.yaml # Monorepo configuration
```
## Development
```bash
# Install dependencies
pnpm install
# Start database and Redis with Docker
docker-compose up -d postgres redis
# Set up individual environment variables
cp apps/isekai-backend/.env.example apps/isekai-backend/.env
cp apps/isekai-frontend/.env.example apps/isekai-frontend/.env
cp apps/isekai-publisher/.env.example apps/isekai-publisher/.env
cp packages/shared/.env.example packages/shared/.env
# Run database migrations
pnpm db:migrate
# Start development servers
pnpm dev
```
### Available Scripts
```bash
# Development
pnpm dev # Start all apps in parallel
pnpm dev:frontend # Start frontend only
pnpm dev:backend # Start backend only
pnpm dev:publisher # Start publisher worker only
pnpm dev:services # Start API + Publisher together
# Building
pnpm build # Build all apps
pnpm build:frontend # Build frontend
pnpm build:backend # Build backend
pnpm build:publisher # Build publisher worker
# Database
pnpm db:generate # Generate database migrations
pnpm db:migrate # Apply database migrations
pnpm db:studio # Open Prisma Studio GUI
# Quality
pnpm lint # Lint all apps
pnpm clean # Clean build artifacts
```
### Docker Services
```bash
# Start all services
docker-compose up -d
# Start specific services
docker-compose up -d postgres redis
# View logs
docker-compose logs -f
# Stop all services
docker-compose down
# Stop and remove volumes
docker-compose down -v
```
## Running on Low-RAM VPS (1GB)
Isekai can run on budget VPS with 1GB RAM using memory optimization. This requires:
### Memory Configuration
Create a `.env` file with these optimized values:
```bash
# PostgreSQL Memory (total: ~180MB)
MEMORY_LIMIT_POSTGRES=180M
MEMORY_RESERVE_POSTGRES=64M
POSTGRES_SHARED_BUFFERS=64MB
POSTGRES_MAX_CONNECTIONS=20
POSTGRES_WORK_MEM=2MB
# Redis Memory (total: ~50MB)
MEMORY_LIMIT_REDIS=50M
REDIS_MAX_MEMORY=32mb
# Backend Node.js (total: ~256MB)
MEMORY_LIMIT_BACKEND=256M
NODE_OPTIONS=--max-old-space-size=256
DB_POOL_SIZE=4
# Publisher Worker (total: ~192MB)
MEMORY_LIMIT_PUBLISHER=192M
PUBLISHER_CONCURRENCY=2
# Frontend nginx (total: ~50MB)
MEMORY_LIMIT_FRONTEND=50M
```
**Total memory usage**: ~730MB + OS overhead = **~850-900MB peak usage**
### System Requirements for 1GB VPS
1. **Add swap file** (critical to prevent OOM kills):
```bash
# Create 2GB swap file
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
# Reduce swappiness (prefer RAM, use swap as safety net)
echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p
```
2. **Use lightweight OS**: Ubuntu Server 22.04 minimal or Alpine Linux
3. **Disable unnecessary services**: Remove snapd, unattended-upgrades if not needed
### Expected Performance
- **Memory**: 700-850MB used, 150-300MB free (+ 2GB swap)
- **CPU**: Low usage (~5-15% idle, peaks during publishing)
- **Publishing**: 2 concurrent jobs (slower than 2GB+ VPS)
- **Response time**: Acceptable for 1-3 users
### When to Upgrade
Upgrade to 2GB+ VPS if you experience:
- Frequent OOM kills (check `dmesg | grep oom`)
- Swap usage consistently >500MB (`free -h`)
- Slow response times (>2s for API calls)
- Publishing job failures due to timeouts
## Documentation
Complete documentation can be accessed at [Isekai Official Website](https://isekai.sh)
## Contributing
We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
### Development Workflow
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Run tests and linting
5. Commit your changes (`git commit -m 'feat: add amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request
## Support
Open an issue to report problems and questions.