Getting Started

Getting Started with Knitly

Installation

Requirements

• Bun (Node.js runtime)
• SQLite3 (usually pre-installed on most systems)
• ffmpeg (optional, for video processing)

Quick Start

1. Clone the Repository

git clone https://github.com/knitly-app/knitly.git
cd knitly

2. Install Dependencies

bun install

3. Start the Development Server

bun run dev

This starts:

• Frontend at http://localhost:5173
• API at http://localhost:3000

4. Create Your First Admin Account

Visit http://localhost:5173 and complete the setup wizard. The wizard also lets you set the instance name and pick a logo icon. To seed an admin from the command line instead:

# Admin account only
bun --cwd server run seed

# Admin plus 20 test users (development)
bun --cwd server run seed:dev

Override the seeded admin credentials with environment variables:

ADMIN_EMAIL=you@example.com ADMIN_PASSWORD=yourpass bun --cwd server run seed

Environment Variables

For development, copy the sample file to .env:

cp .env.sample .env

For production, use the production template:

cp deploy/env.production.example server/.env.production

Required Variables (production)

Variable	Example	Description
NODE_ENV	production	Environment mode
PORT	3000	API server port
BASE_URL	https://your-domain.com	Public URL
ALLOWED_ORIGINS	https://your-domain.com	CORS whitelist

Database

Variable	Default	Description
DATABASE_PATH	../knitly.db	SQLite file path

Storage

Local Filesystem (default):

Variable	Default	Description
USE_LOCAL_STORAGE	true	Use local storage
LOCAL_UPLOAD_DIR	../uploads	Media upload directory

S3-Compatible Storage:

Variable	Description
SPACES_ENDPOINT	S3 endpoint (e.g., nyc3.digitaloceanspaces.com)
SPACES_REGION	S3 region (e.g., nyc3)
SPACES_BUCKET	Bucket name
SPACES_KEY	Access key
SPACES_SECRET	Secret key
SPACES_PUBLIC_URL	CDN URL for uploads

Deployment Options

Docker

# Build and run
docker compose up -d

# View logs
docker compose logs -f

Environment variables should be set in docker-compose.yml:

environment:
  - NODE_ENV=production
  - BASE_URL=https://your-domain.com
  - ALLOWED_ORIGINS=https://your-domain.com

Bare Metal (systemd)

1. Install dependencies:

# Ubuntu/Debian
sudo apt install sqlite3 ffmpeg

# Arch Linux
sudo pacman -S sqlite ffmpeg

2. Build and deploy:

bun install
bun run build

3. Create systemd service:

sudo cp deploy/knitly.service /etc/systemd/system/
sudo systemctl edit knitly.service

4. Configure environment:

sudo mkdir -p /etc/knitly
sudo cp deploy/env.production.example /etc/knitly/.env
sudo nano /etc/knitly/.env  # Edit with your values

5. Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable knitly
sudo systemctl start knitly

Reverse Proxy (Caddy)

Example Caddyfile:

knitly.example.com {
    reverse_proxy localhost:3000
}

First Run

1. Visit your domain
2. Complete the setup wizard (create the admin account, set the instance name and logo icon)
3. Invite others via the admin panel
4. Adjust the instance name and logo icon later in admin settings

Updating

Git Update

git pull origin main
bun install  # if dependencies changed
bun run build
bun run start  # or restart systemd

Docker Update

docker compose pull
docker compose up -d

Troubleshooting

Port Already in Use

# Find process using port 3000
lsof -i :3000
# or
netstat -tulpn | grep :3000

Database Schema

Knitly has no migration tool. It creates its SQLite tables programmatically on startup, so a fresh database is ready on first run. Back up the file before upgrading:

cp knitly.db knitly.db.backup

Logs

# Development
bun run dev  # logs to console

# Production (systemd)
journalctl -u knitly -f

# Docker
docker compose logs -f

Next Steps

1. Configuration - Deep dive into settings
2. Custom Extensions - Add deployment-specific features
3. API Documentation - Programmatic access
4. Contributing - Development