trace.moe-api

March 7, 2026 ยท View on GitHub

License GitHub Workflow Status Docker Docker Image Size Discord

API server for trace.moe

API Docs

Features

  • serve image search request
  • crop black borders on search images
  • rate limiting and user management
  • serve index and database status
  • store and serve compressed hash files
  • distribute hash jobs to workers

Prerequisites

  • Node.js >= 22.15
  • PostgreSQL 17+
  • Milvus 2.6.0+
  • FFmpeg
  • Docker

Install

Install Prerequisites first, then:

git clone https://github.com/soruly/trace.moe-api.git
cd trace.moe-api
npm install

Getting Started

  • Copy .env.example to .env
  • Edit .env as appropriate for your setup, i.e. VIDEO_PATH.
  • Change TRACE_API_SALT to a unique value of at least 32 characters.
  • docker compose up -d
  • node server.ts

On the first start, it will create all database tables in postgresql and create the collection in milvus. On every start, it will scan the VIDEO_PATH for new video files (.mp4, .mkv, or .webm) and re-scan the VIDEO_PATH every minute for new video files.

Run as systemd

Put this file to /etc/systemd/system/trace.moe-api.service

[Unit]
Description=trace.moe-api
Wants=network-online.target
After=network-online.target

[Service]
User=____
Group=____
WorkingDirectory=/home/____/project/trace.moe-api
Environment=NODE_ENV=production
ExecStart=/usr/bin/node --dns-result-order=ipv6first /home/____/project/trace.moe-api/server.ts
Restart=always

[Install]
WantedBy=multi-user.target