Skip to main content

​
Installation

This guide covers installing Kitsu for both production use and development. Choose the installation method that best fits your needs. Docker provides the simplest way to run Kitsu with all dependencies pre-configured.

​
Prerequisites

  • Docker >= 1.13
  • Port 80 available on your host machine (or configure a different port)

​
Basic setup

Run the CGWire Docker image: 
docker run -d --rm -p 80:80 --name cgwire cgwire/cgwire
Access Kitsu at http://localhost after the container starts (approximately 30 seconds).

​
Custom port configuration

If port 80 is already in use, map to a different port: 
docker run -d --rm -p 8080:80 --name cgwire cgwire/cgwire
Access Kitsu at http://localhost:8080.

​
Persistent data

By default, data is stored inside the container. For production use, mount volumes to persist data: 
docker run -d \
  -p 80:80 \
  --name cgwire \
  -v kitsu-db:/var/lib/postgresql \
  -v kitsu-storage:/opt/zou/storage \
  cgwire/cgwire
Always use volume mounts for production deployments to prevent data loss when containers are recreated.

​
Development environment

Set up a local development environment to contribute to Kitsu or customize it for your studio.

​
Prerequisites

Ensure you have the following installed:
  • Node.js: >= 20.19 (Download)
  • npm: >= 10 (comes with Node.js)
  • Docker: >= 1.13 (for the API backend)
  • Git: For cloning the repository
The specific version requirements come from the engines field in package.json:1:95. Using older versions may cause compatibility issues.

​
Installation steps

1

Start the API backend

Run the CGWire Docker container to provide the API and database:
docker run -d --rm -p 80:80 --name cgwire cgwire/cgwire
This provides the Zou API that Kitsu connects to.
2

Configure environment variables

Set up the API connection. The development server needs to know where to find the backend:
export KITSU_API_TARGET=http://localhost/api
export KITSU_EVENT_TARGET=http://localhost/socket.io
These environment variables are used by the Vite proxy configuration in vite.config.js:40-49 to forward API requests to the backend.
3

Clone the repository

Get the Kitsu source code from GitHub:
git clone https://github.com/cgwire/kitsu.git
cd kitsu
4

Install dependencies

Install all required npm packages:
npm install
This installs Vue.js, Vuex, Vite, and all other dependencies listed in package.json.
5

Start the development server

Launch the Vite development server:
npm run dev
After a few seconds, Vite will start the development server at http://127.0.0.1:8080.
The development server includes hot module replacement (HMR), so your changes will automatically reload in the browser as you edit files.

​
Development server configuration

The Vite development server is configured in vite.config.js with:
  • Host: 127.0.0.1
  • Port: 8080
  • API proxy: Forwards /api requests to the backend
  • WebSocket proxy: Forwards /socket.io for real-time updates

​
Available scripts

The package.json defines several useful development commands: 
npm run dev

​
Environment variables

Kitsu uses environment variables for configuration:
VariableDescriptionDefault
KITSU_API_TARGETBackend API endpoint URLhttp://127.0.0.1:5000
KITSU_EVENT_TARGETWebSocket server URL for real-time eventshttp://127.0.0.1:5001
These variables are only used during development. In production, the Kitsu frontend and Zou API are typically served from the same domain.

​
Architecture overview

Kitsu follows a modern frontend architecture:
  • Vue Router: Manages URL routes and navigation
  • Vuex stores: Centralized state management with mutations and actions
  • Components: Reusable UI elements with HTML, CSS, and JavaScript
  • WebSocket: Real-time updates via Socket.io
  • API client: Superagent for HTTP requests to the Zou backend
Key architectural principles:
  1. URL routes provide the main application context
  2. Shared state is stored in Vuex stores
  3. Mutations modify state synchronously
  4. Actions handle asynchronous operations (API calls, etc.)
  5. Components access state through getters
  6. Local UI state is managed within components

​
Troubleshooting

​
Port already in use

Problem: Port 8080 is already occupied. Solution: Edit vite.config.js and change the port number: 
server: {
  host: '127.0.0.1',
  port: 3000, // Change to any available port
  // ...
}

​
Cannot connect to API

Problem: Frontend cannot reach the backend API. Solution: Verify the Docker container is running and check the environment variables: 
# Check container status
docker ps | grep cgwire

# Verify environment variables
echo $KITSU_API_TARGET
echo $KITSU_EVENT_TARGET

​
JavaScript required error

Problem: Browser shows “JavaScript required” message. Solution: Ensure JavaScript is enabled in your browser. Kitsu is a single-page application that requires JavaScript to function.

​
Node version mismatch

Problem: npm install fails due to Node.js version. Solution: Upgrade to Node.js >= 20.19: 
# Check current version
node --version

# Install using nvm (recommended)
nvm install 20.19
nvm use 20.19

​
Build errors after git pull

Problem: Development server fails after updating code. Solution: Clean install dependencies: 
rm -rf node_modules package-lock.json
npm install
npm run dev

​
Production deployment

For production environments:
  1. Use persistent volumes for database and file storage
  2. Configure backups for your PostgreSQL database
  3. Set up SSL/TLS using a reverse proxy (nginx, Caddy, etc.)
  4. Change default passwords for all accounts
  5. Configure email for notifications and password resets
  6. Monitor logs for errors and performance issues
The Docker quickstart is suitable for testing but requires additional configuration for production use. Consider database backups, SSL certificates, and security hardening.

​
Next steps

Contributing guide

Learn how to contribute code to Kitsu

API documentation

Explore the Zou API for integrations

Community Discord

Get help from the Kitsu community

Feature requests

Suggest new features on Canny

Build docs developers (and LLMs) love

Get started for freeTalk to us