Tinykit

https://docs.tinykit.studio/
Admin
Tinykit is an open-source, self-hosted platform for building and deploying tiny web applications...
Tokens:24,506
Snippets:376
Trust Score:4.3
Update:4 months ago
Show doc for...
Tokens:
Raw
### Setup Production Server with PM2

Source: https://docs.tinykit.studio/vps

Installs PM2 globally, creates an ecosystem configuration file for tinykit, and starts the server using PM2 for persistent running and automatic restarts.

```bash
# Install PM2 globally
npm install -g pm2

# Create PM2 ecosystem file
cat > ecosystem.config.js << 'EOF'
module.exports = {
  apps: [{
    name: 'tinykit',
    script: './deploy/railway/start.sh',
    cwd: '/path/to/tinykit',
    env: {
      NODE_ENV: 'production',
      PORT: 3000,
      HOST: '0.0.0.0'
    },
    // Restart on failure
    restart_delay: 5000,
    max_restarts: 10,
    // Logging
    error_file: './logs/error.log',
    out_file: './logs/out.log',
    merge_logs: true,
    time: true
  }]
}
EOF

# Start with PM2
pm2 start ecosystem.config.js

# Save PM2 config (survives reboot)
pm2 save

# Enable PM2 startup on boot
pm2 startup
```

--------------------------------

### Personal Projects Domain Setup

Source: https://docs.tinykit.studio/domain-routing

Example scenario for organizing personal projects using different subdomains of a single domain.

```text
# Different subdomains of your domain
recipes.mydomain.com    → Recipe collection
bookmarks.mydomain.com  → Bookmark manager
notes.mydomain.com      → Note-taking app
```

--------------------------------

### Start tinykit Server (Testing)

Source: https://docs.tinykit.studio/vps

Makes the start script executable and then runs it to start the tinykit server for testing purposes.

```bash
# Make start script executable
chmod +x deploy/railway/start.sh

# Start (for testing)
./deploy/railway/start.sh
```

--------------------------------

### Agency Client Domain Setup

Source: https://docs.tinykit.studio/domain-routing

Example scenario for an agency managing multiple client websites on a single Tinykit instance.

```text
# Your clients' domains
client-a.com     → Portfolio site
client-b.com     → Booking system
client-c.com     → Product catalog

# Your internal tools (subdomain)
admin.youragency.com → Internal dashboard
crm.youragency.com   → Client CRM
```

--------------------------------

### Google (Gemini) Provider Example

Source: https://docs.tinykit.studio/configuration

Example environment variables for configuring the Google Gemini provider.

```bash
LLM_PROVIDER=gemini
LLM_API_KEY=your-gemini-api-key
LLM_MODEL=gemini-pro
```

--------------------------------

### Complete Production .env File Example

Source: https://docs.tinykit.studio/configuration

A comprehensive example of a `.env` file for a production environment, including AI, database, and server settings.

```bash
# AI Configuration
LLM_PROVIDER=anthropic
LLM_API_KEY=sk-ant-api03-...
LLM_MODEL=claude-sonnet-4-20250514

# Database
POCKETBASE_ADMIN_EMAIL=admin@yourdomain.com
POCKETBASE_ADMIN_PASSWORD=your-secure-password-here

# Server (usually set by platform)
PORT=3000
HOST=0.0.0.0
```

--------------------------------

### OpenAI (GPT-4) Provider Example

Source: https://docs.tinykit.studio/configuration

Example environment variables for configuring the OpenAI provider with GPT-4.

```bash
LLM_PROVIDER=openai
LLM_API_KEY=sk-...
LLM_MODEL=gpt-4
```

--------------------------------

### Start Tinykit Studio Container

Source: https://docs.tinykit.studio/docker

Manually start the Tinykit Studio container with volume mounts, environment variables, and port mapping.

```bash
docker stop tinykit
docker rm tinykit
docker run -d \
  -v tinykit-data:/app/pocketbase/pb_data \
  --env-file .env.production \
  -p 3000:3000 \
  --name tinykit \
  tinykit
```

--------------------------------

### Complete Todo List Application Example

Source: https://docs.tinykit.studio/data-fetching

A full-stack example demonstrating realtime data binding, adding, toggling, and deleting todos using the $data import.

```svelte
<script>
  import data from '$data'

  let todos = $state([])
  let loading = $state(true)
  let new_title = $state('')

  data.todos.subscribe(items => {
    todos = items
    loading = false
  })

  async function add_todo() {
    if (!new_title.trim()) return
    await data.todos.create({
      title: new_title,
      completed: false
    })
    new_title = ''
  }

  async function toggle_todo(todo) {
    await data.todos.update(todo.id, {
      completed: !todo.completed
    })
  }

  async function delete_todo(id) {
    await data.todos.delete(id)
  }
</script>

<input bind:value={new_title} placeholder="New todo" />
<button onclick={add_todo}>Add</button>

{#each todos as todo (todo.id)}
  <div>
    <input
      type="checkbox"
      checked={todo.completed}
      onchange={() => toggle_todo(todo)}
    />
    <span>{todo.title}</span>
    <button onclick={() => delete_todo(todo.id)}>Delete</button>
  </div>
{/each}
```

--------------------------------

### Build and Start with Docker Compose

Source: https://docs.tinykit.studio/docker

Use Docker Compose to build the image and start the Tinykit Studio service in detached mode.

```bash
git pull
docker compose build
docker compose up -d
```

--------------------------------

### Self-hosted VPS Deployment Commands

Source: https://docs.tinykit.studio/architecture

Steps to clone the repository, install dependencies, build the project, and run it for self-hosted deployment.

```bash
git clone https://github.com/tinykit-studio/tinykit.git
cd tinykit
npm install
npm run build
npm run preview
```

--------------------------------

### Install nginx Web Server

Source: https://docs.tinykit.studio/vps

Installs the nginx web server on Ubuntu/Debian systems.

```bash
# Install nginx
sudo apt install nginx
```

--------------------------------

### Clone tinykit and Install Dependencies

Source: https://docs.tinykit.studio/vps

Clones the tinykit repository, navigates into the directory, installs project dependencies, and builds the project for production.

```bash
# Clone repository
git clone https://github.com/tinykit-studio/tinykit.git
cd tinykit

# Install dependencies
npm install

# Build for production
npm run build
```

--------------------------------

### Install Project Dependencies

Source: https://docs.tinykit.studio/quickstart

Install the necessary Node.js dependencies for the Tinykit project. This command should be run after cloning the repository.

```bash
npm install
```

--------------------------------

### Anthropic (Claude) Provider Example

Source: https://docs.tinykit.studio/configuration

Example environment variables for configuring the Anthropic provider.

```bash
LLM_PROVIDER=anthropic
LLM_API_KEY=sk-ant-api03-...
LLM_MODEL=claude-sonnet-4-20250514
```

--------------------------------

### Install Node.js on Ubuntu/Debian

Source: https://docs.tinykit.studio/vps

Installs Node.js version 20.x.x on Ubuntu or Debian systems. Verifies the installation.

```bash
# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verify
node --version  # Should be v20.x.x
npm --version
```

--------------------------------

### App Creation Redirect Example

Source: https://docs.tinykit.studio/domain-routing

Demonstrates the redirect URL when a domain is accessed for the first time and no app is associated with it.

```text
Visit: recipes.yourserver.com
Redirect to: /tinykit/new?domain=recipes.yourserver.com
```

--------------------------------

### Run Tinykit Studio with Resource Limits

Source: https://docs.tinykit.studio/docker

Start the Tinykit Studio container with specified memory and CPU limits.

```bash
docker run -d \
  --memory="1g" \
  --cpus="1.0" \
  tinykit
```

--------------------------------

### Run Tinykit Development Server

Source: https://docs.tinykit.studio/quickstart

Start the development server for Tinykit. Access the application at http://localhost:5173/tinykit.

```bash
npm run dev
```

--------------------------------

### Example Domain Mappings

Source: https://docs.tinykit.studio/domain-routing

Map different domains to specific applications within your Tinykit instance.

```text
recipes.yourserver.com     → Recipe app
blog.yourserver.com        → Blog app
calculator.yourserver.com  → Calculator app
crm.yourserver.com         → CRM app
```

--------------------------------

### Configure Environment Variables

Source: https://docs.tinykit.studio/vps

Copies the example environment file and instructs to edit it with specific settings for LLM provider, API key, model, port, and host.

```bash
# Copy example config
cp .env.example .env

# Edit with your settings
nano .env
```

```bash
LLM_PROVIDER=anthropic
LLM_API_KEY=sk-ant-...
LLM_MODEL=claude-sonnet-4-20250514
PORT=3000
HOST=0.0.0.0
```

--------------------------------

### Install Caddy Web Server

Source: https://docs.tinykit.studio/vps

Installs the Caddy web server on Ubuntu/Debian systems. This is recommended for automatic SSL certificate management.

```bash
# Install Caddy
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy
```

--------------------------------

### Domain Normalization Examples

Source: https://docs.tinykit.studio/domain-routing

Shows how Tinykit normalizes domain names for consistent routing, including removing prefixes and port numbers.

```text
recipes.yourserver.com
www.recipes.yourserver.com
RECIPES.yourserver.com
recipes.yourserver.com:443
```

--------------------------------

### Download PocketBase Binary

Source: https://docs.tinykit.studio/quickstart

Download the PocketBase binary, which is required for local database setup in Tinykit.

```bash
npm run pocketbase:download
```

--------------------------------

### Multi-App Routing Example

Source: https://docs.tinykit.studio/features

Demonstrates how TinyKit serves multiple applications from a single instance using domain-based routing. Point any domain to your TinyKit server to automatically serve the correct app.

```text
recipes.yourserver.com/        → Serves recipe app
recipes.yourserver.com/tinykit → Edit recipe app

blog.yourserver.com/           → Serves blog app
blog.yourserver.com/tinykit    → Edit blog app

calculator.yourserver.com/     → Serves calculator app
...
```

--------------------------------

### DNS Configuration Examples

Source: https://docs.tinykit.studio/domain-routing

Configure DNS records to point your domains to your Tinykit server's IP address or hostname.

```text
recipes.yourserver.com    A    → 123.45.67.89
blog.yourserver.com       A    → 123.45.67.89
calculator.yourserver.com A    → 123.45.67.89
```

```text
recipes.yourserver.com    CNAME → your-app.railway.app
```

--------------------------------

### Caddyfile Configuration for Tinykit

Source: https://docs.tinykit.studio/docker

Example Caddyfile to configure reverse proxying to the Tinykit service. Replace 'app.yourdomain.com' with your actual domain.

```plaintext
app.yourdomain.com {
  reverse_proxy tinykit:3000
}
```

--------------------------------

### Docker Deployment Dockerfile

Source: https://docs.tinykit.studio/architecture

A Dockerfile to build a Node.js image, install dependencies, build the project, and run the preview command.

```dockerfile
FROM node:20-alpine
WORKDIR /app
COPY . .
RUN npm install && npm run build
CMD ["npm", "run", "preview"]
```

--------------------------------

### Domain-Based Routing Example

Source: https://docs.tinykit.studio/architecture

Illustrates how Tinykit handles multiple applications by associating different domains with distinct projects. Each domain serves its respective app at the root and provides access to the studio at the /tinykit path.

```text
calculator.myserver.com/           → Serves calculator app
calculator.myserver.com/tinykit    → Edit calculator app

blog.myserver.com/                 → Serves blog app
blog.myserver.com/tinykit          → Edit blog app

recipes.myserver.com/              → Serves recipes app
recipes.myserver.com/tinykit       → Edit recipes app
```

--------------------------------

### Manage Systemd Service for Tinykit

Source: https://docs.tinykit.studio/vps

Commands to manage the systemd service. Reloads systemd configuration, enables the service to start on boot, starts the service, checks its status, and views its logs.

```bash
# Reload systemd
sudo systemctl daemon-reload

# Enable on boot
sudo systemctl enable tinykit

# Start
sudo systemctl start tinykit

# Check status
sudo systemctl status tinykit

# View logs
sudo journalctl -u tinykit -f
```

--------------------------------

### Domain-Based Routing Example

Source: https://docs.tinykit.studio/faq

Demonstrates how to configure domain-based routing to serve multiple applications from a single Tinykit instance. Point different subdomains to your server, and Tinykit will automatically route requests to the correct app.

```text
recipes.yourserver.com → Recipe app
blog.yourserver.com    → Blog app
crm.yourserver.com     → CRM app
```

--------------------------------

### Tinykit Production Dockerfile

Source: https://docs.tinykit.studio/docker

This Dockerfile is optimized for production, installing dependencies, copying the application, building it, setting up runtime directories, and exposing the application port.

```dockerfile
FROM node:20-alpine

WORKDIR /app

# Install dependencies
COPY package*.json ./
RUN npm ci --production=false

# Copy app
COPY . .

# Build
RUN npm run build

# Create directories for runtime
RUN mkdir -p pocketbase/pb_data workspace

# Expose port
EXPOSE 3000
ENV PORT=3000
ENV HOST=0.0.0.0

# Start
CMD ["./start.sh"]
```

--------------------------------

### Create Systemd Service for Tinykit

Source: https://docs.tinykit.studio/vps

Defines a systemd service to manage the Tinykit application, ensuring it starts automatically and restarts on failure. Configure environment variables and paths as needed.

```bash
sudo nano /etc/systemd/system/tinykit.service
```

--------------------------------

### Responsive CSS Layout with Flexbox

Source: https://docs.tinykit.studio/no-api-key

Example of a mobile-first CSS approach using flexbox for layout, with different styles for small screens and larger breakpoints.

```css
.container { padding: 1rem; }
.grid { display: flex; flex-direction: column; gap: 1rem; }

@media (min-width: 768px) {
  .container { padding: 2rem; }
  .grid { flex-direction: row; }
}
```

--------------------------------

### CSS Fallback Example

Source: https://docs.tinykit.studio/design-system

Demonstrates how CSS will fall back to a default value if a referenced design field is deleted. Always ensure fallbacks are specified.

```css
var(--deleted-field, fallback)
```

--------------------------------

### Troubleshoot Port Already in Use

Source: https://docs.tinykit.studio/vps

Identifies and terminates processes using a specific port (e.g., 3000). Useful for resolving conflicts when starting an application.

```bash
# Check what's using the port
sudo lsof -i :3000

# Kill the process or change the PORT in your config.
```

--------------------------------

### Subscribe to Realtime Database Updates

Source: https://docs.tinykit.studio/data-fetching

Use data.collection.subscribe to get realtime updates from your database. This is useful for displaying lists that change frequently.

```svelte
<script>
  import data from '$data'

  let todos = $state([])
  let loading = $state(true)

  // Subscribe to realtime updates
  data.todos.subscribe(items => {
    todos = items
    loading = false
  })
</script>

{#if loading}
  <p>Loading...</p>
{:else}
  {#each todos as todo (todo.id)}
    <p>{todo.title}</p>
  {/each}
{/if}
```

--------------------------------

### Docker Compose with Caddy Reverse Proxy

Source: https://docs.tinykit.studio/docker

Configure Docker Compose to run Tinykit alongside Caddy as a reverse proxy for production deployments. This setup handles SSL termination and routing.

```yaml
version: '3.8'

services:
  tinykit:
    build:
      context: .
      dockerfile: deploy/docker/Dockerfile
    environment:
      - LLM_PROVIDER=anthropic
      - LLM_API_KEY=${LLM_API_KEY}
      - POCKETBASE_ADMIN_EMAIL=admin@example.com
      - POCKETBASE_ADMIN_PASSWORD=${POCKETBASE_ADMIN_PASSWORD}
    volumes:
      - tinykit-data:/app/pocketbase/pb_data
    restart: unless-stopped

  caddy:
    image: caddy:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - caddy-data:/data
    restart: unless-stopped

volumes:
  tinykit-data:
  caddy-data:
```

--------------------------------

### Docker Compose Management Commands

Source: https://docs.tinykit.studio/docker

Commands to manage the Tinykit service using Docker Compose, including starting services in detached mode, viewing logs, and stopping services.

```bash
# Set secrets in environment or .env file
export LLM_API_KEY=sk-ant-...
export POCKETBASE_ADMIN_PASSWORD=securepassword123

# Start
docker compose up -d

# View logs
docker compose logs -f

# Stop
docker compose down
```

--------------------------------

### Docker Compose with Nginx Reverse Proxy

Source: https://docs.tinykit.studio/docker

Example Docker Compose configuration snippet for integrating Tinykit with an Nginx reverse proxy. This requires a separate nginx service definition and configuration file.

```yaml
services:
  tinykit:
    # ... same as above

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
      - /etc/letsencrypt:/etc/letsencrypt
    restart: unless-stopped
```

--------------------------------

### Using Prefixes for Unique Collection Names

Source: https://docs.tinykit.studio/database

Suggests a naming convention for collections to avoid naming conflicts when multiple apps share the same database instance. Examples include 'recipes_items', 'blog_posts', and 'crm_contacts'.

```plaintext
recipes_items      (recipes app)
blog_posts         (blog app)
crm_contacts       (crm app)
```

--------------------------------

### Update Tinykit Project

Source: https://docs.tinykit.studio/vps

Steps to update the Tinykit project. Navigates to the project directory, pulls the latest code, installs new dependencies, rebuilds the project, and restarts the application using PM2 or systemd.

```bash
cd /path/to/tinykit

# Pull latest
git pull

# Install new dependencies
npm install

# Rebuild
npm run build

# Restart
pm2 restart tinykit
# or
sudo systemctl restart tinykit
```

--------------------------------

### Build and Run Tinykit Docker Container

Source: https://docs.tinykit.studio/docker

Clone the repository, build the Docker image, and run the container with essential environment variables and port mapping. Access the application at http://localhost:3000/tinykit.

```bash
# Clone the repository
git clone https://github.com/tinykit-studio/tinykit.git
cd tinykit

# Build the image
docker build -f deploy/docker/Dockerfile -t tinykit .

# Run the container
docker run -d \
  -p 3000:3000 \
  -e LLM_PROVIDER=anthropic \
  -e LLM_API_KEY=your-api-key \
  -e POCKETBASE_ADMIN_EMAIL=admin@example.com \
  -e POCKETBASE_ADMIN_PASSWORD=your-password \
  -v tinykit-data:/app/pocketbase/pb_data \
  --name tinykit \
  tinykit
```

--------------------------------

### Configure Tinykit with Docker Environment Variables

Source: https://docs.tinykit.studio/configuration

Run a Docker container and pass environment variables using the -e flag. Ensure all required variables for LLM and PocketBase are set.

```bash
docker run -d \
  -e LLM_PROVIDER=anthropic \
  -e LLM_API_KEY=sk-ant- \
  -e POCKETBASE_ADMIN_EMAIL=admin@example.com \
  -e POCKETBASE_ADMIN_PASSWORD=password \
  tinykit
```

--------------------------------

### Local Development Host File Configuration

Source: https://docs.tinykit.studio/domain-routing

Configure your local hosts file to simulate domain routing during development.

```text
127.0.0.1 recipes.local
127.0.0.1 blog.local
```

--------------------------------

### Run Tinykit with an Environment File

Source: https://docs.tinykit.studio/docker

Manage environment variables by creating a .env.production file and using the --env-file flag with docker run. This approach centralizes configuration for easier management.

```bash
# Create .env.production
cat > .env.production << EOF
LLM_PROVIDER=anthropic
LLM_API_KEY=sk-ant-...
LLM_MODEL=claude-sonnet-4-20250514
POCKETBASE_ADMIN_EMAIL=admin@example.com
POCKETBASE_ADMIN_PASSWORD=securepassword123
EOF

# Run with env file
docker run -d --env-file .env.production tinykit
```

--------------------------------

### Docker Volume Snapshot for Backups

Source: https://docs.tinykit.studio/security

Create backups of Pocketbase data by taking a snapshot of the Docker volume. This method allows for direct backup and restore operations.

```bash
# Create backup
docker run --rm \
  -v tinykit-data:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/pb_data_$(date +%Y%m%d).tar.gz -C /data .

# Restore from backup
docker run --rm \
  -v tinykit-data:/data \
  -v $(pwd):/backup \
  alpine sh -c "cd /data && tar xzf /backup/pb_data_20231215.tar.gz"
```

--------------------------------

### Styling Content with Design Fields in Svelte

Source: https://docs.tinykit.studio/content-fields

Combine content fields with design fields to apply styles directly. This example applies a CSS variable to a heading.

```svelte
<h1 style="color: var(--heading-color)">
  {content.hero_title}
</h1>
```

--------------------------------

### Automated Daily Database Backup with Cron

Source: https://docs.tinykit.studio/vps

Sets up a daily automated backup of the PocketBase database using cron. It copies the pb_data directory at 2 AM and deletes backups older than 7 days at 3 AM.

```bash
# Add to crontab
crontab -e
```

```crontab
# Daily backup at 2 AM
0 2 * * * cp -r /path/to/tinykit/pocketbase/pb_data /backup/tinykit-$(date +%Y%m%d)

# Keep only last 7 days
0 3 * * * find /backup -name "tinykit-*" -mtime +7 -delete
```

--------------------------------

### Inspect Volume Mounts

Source: https://docs.tinykit.studio/docker

Inspect the 'tinykit' container to verify that volume mounts are correctly configured for data persistence.

```bash
docker inspect tinykit | grep Mounts -A 20
```

--------------------------------

### Nginx Reverse Proxy Configuration

Source: https://docs.tinykit.studio/domain-routing

Configure Nginx as a reverse proxy for self-hosted applications, including SSL certificate setup and request forwarding. Ensure you have SSL certificates generated.

```nginx
server {
  listen 443 ssl;
  server_name recipes.yourserver.com blog.yourserver.com;

  ssl_certificate /path/to/cert.pem;
  ssl_certificate_key /path/to/key.pem;

  location / {
    proxy_pass http://localhost:5173;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
  }
}
```

--------------------------------

### Configure Firewall with UFW

Source: https://docs.tinykit.studio/vps

Commands to set up the Uncomplicated Firewall (UFW). Allows HTTP, HTTPS, and a custom port (e.g., 3000), then enables the firewall.

```bash
# Allow HTTP/HTTPS
sudo ufw allow 80
sudo ufw allow 443

# Or allow custom port
sudo ufw allow 3000

# Enable firewall
sudo ufw enable
```

--------------------------------

### Clone Tinykit Repository

Source: https://docs.tinykit.studio/quickstart

Clone the Tinykit repository to your local machine. This is the first step for local development.

```bash
git clone https://github.com/tinykit-studio/tinykit.git
cd tinykit
```

--------------------------------

### Fly.io Deployment Commands

Source: https://docs.tinykit.studio/architecture

Commands to launch, set secrets, and deploy the application using Fly.io.

```bash
fly launch
fly secrets set LLM_API_KEY=sk-...
fly deploy
```

--------------------------------

### Configure Tinykit with PM2 Ecosystem File

Source: https://docs.tinykit.studio/configuration

Set environment variables within the ecosystem.config.js file for PM2 deployments. This method is suitable for VPS deployments managed by PM2.

```javascript
module.exports = {
  apps: [{
    name: 'tinykit',
    script: './start.sh',
    env: {
      LLM_PROVIDER: 'anthropic',
      LLM_API_KEY: 'sk-ant-...',
      // ...
    }
  }]
}
```

--------------------------------

### Filtering Data with $derived.by()

Source: https://docs.tinykit.studio/database

Filter data dynamically based on user interaction or application state. This example shows filtering a list of todos based on a 'show_completed' flag using $derived.by() for efficient reactivity.

```svelte
<script>
  import data from '$data'

  let todos = $state([])
  let show_completed = $state(false)

  data.todos.subscribe(items => {
    todos = items
  })

  // Filter with $derived.by() for callbacks
  let visible_todos = $derived.by(() =>
    todos.filter(t => show_completed || !t.completed)
  )
</script>
```

--------------------------------

### Troubleshoot Pocketbase Permissions

Source: https://docs.tinykit.studio/vps

Ensures the Pocketbase binary has execute permissions and checks file listing. Verifies the binary architecture matches the system.

```bash
chmod +x pocketbase/pocketbase
ls -la pocketbase/
```

--------------------------------

### Persist Tinykit Data with Bind Mount

Source: https://docs.tinykit.studio/docker

Alternatively, use a bind mount to map a specific directory on the host machine to /app/pocketbase/pb_data for data persistence. Ensure the host directory exists.

```bash
docker run -d \
  -v /path/on/host/pb_data:/app/pocketbase/pb_data \
  tinykit
```

--------------------------------

### Check Container Logs

Source: https://docs.tinykit.studio/docker

View the logs of the 'tinykit' container to diagnose immediate exit issues.

```bash
docker logs tinykit
```

--------------------------------

### AI Agent Tool-Use Pattern

Source: https://docs.tinykit.studio/architecture

Illustrates the workflow of the AI agent, showing how it receives prompts, calls tools, and processes results to build applications.

```text
You: "Add a contact form"
         │
         ▼
┌─────────────────────────────┐
│  LLM receives:              │
│  - Your prompt              │
│  - Current code       │
│  - Design/content fields    │
│  - Conversation history     │
└─────────────────────────────┘
         │
         ▼
┌─────────────────────────────┐
│  LLM calls tools:           │
│  - write_code               │
│  - create_design_field      │
│  - create_content_field     │
│  - create_data_file         │
└─────────────────────────────┘
         │
         ▼
┌─────────────────────────────┐
│  Tools execute              │
│  Results fed back           │
│  Loop until done            │
└─────────────────────────────┘
         │
         ▼
    Response streamed to you
```

--------------------------------

### Prompt Template for LLM App Generation

Source: https://docs.tinykit.studio/no-api-key

Use this template to instruct LLMs like Claude or ChatGPT to generate a tinykit app. Ensure the output is valid JSON matching the specified structure.

```markdown
Create a tinykit app: [DESCRIBE YOUR APP HERE]

Output valid JSON with this exact structure:

```json
{
  "description": "App name",
  "frontend_code": "SVELTE_5_COMPONENT_HERE",
  "design": [],
  "content": [],
  "collections": []
}
```
```

--------------------------------

### Request Flow for Domain Routing

Source: https://docs.tinykit.studio/domain-routing

Illustrates the process Tinykit follows when a request arrives, from domain extraction to serving the correct project.

```text
Request: recipes.yourserver.com/
         │
         ▼
Domain lookup: "recipes.yourserver.com"
         │
         ▼
Find project with matching domain
         │
         ▼
Serve project as static file (compiled HTML)
```

--------------------------------

### Bash Script for Pocketbase Backups via Docker

Source: https://docs.tinykit.studio/security

Automate Pocketbase database backups using a bash script with Docker. This script stops writes, copies the backup, and retains the last 7 days of backups.

```bash
# backup.sh
#!/bin/bash
BACKUP_DIR="/path/to/backups"
CONTAINER="tinykit"
DATE=$(date +%Y%m%d_%H%M%S)

# Stop writes temporarily (optional, for consistency)
docker exec $CONTAINER /app/pocketbase/pocketbase backup

# Copy the backup
docker cp $CONTAINER:/app/pocketbase/pb_data/backups/. $BACKUP_DIR/

# Keep only last 7 days
find $BACKUP_DIR -name "*.zip" -mtime +7 -delete
```

--------------------------------

### Troubleshoot Permission Denied Errors

Source: https://docs.tinykit.studio/vps

Fixes permission denied errors by ensuring the current user owns the Tinykit project directory. Use this command to recursively change ownership.

```bash
sudo chown -R $USER:$USER /path/to/tinykit
```

--------------------------------

### Data API for Realtime Subscriptions and CRUD

Source: https://docs.tinykit.studio/no-api-key

Shows how to import the data API to subscribe to realtime updates for collections and perform Create, Read, Update, and Delete operations.

```javascript
import data from '$data'

// Subscribe for realtime updates (returns unsubscribe fn)
$effect(() => data.todos.subscribe(items => { todos = items; loading = false }))

// CRUD - realtime auto-updates UI
await data.todos.create({ title: 'New' })
await data.todos.update(id, { done: true })
await data.todos.delete(id)
```

--------------------------------

### Accessing Builder for Current Domain

Source: https://docs.tinykit.studio/domain-routing

How to access the builder interface for the application associated with the current domain.

```text
recipes.yourserver.com/tinykit
```

--------------------------------

### Proxy API for External Data and Media

Source: https://docs.tinykit.studio/no-api-key

Illustrates using the proxy API to fetch external data as JSON or text, and to generate URLs for media assets.

```javascript
import { proxy } from '$tinykit'

const data = await proxy.json('https://api.example.com/data')  // JSON
const rss = await proxy.text('https://hnrss.org/frontpage')    // text/RSS/XML
<audio src={proxy.url('https://example.com/audio.mp3')} />     // media URLs
```

--------------------------------

### Set Server Host

Source: https://docs.tinykit.studio/configuration

Define the host address the server binds to. `0.0.0.0` binds to all interfaces, while `127.0.0.1` restricts it to localhost.

```bash
HOST=0.0.0.0
```

--------------------------------

### Configure nginx Reverse Proxy

Source: https://docs.tinykit.studio/vps

Creates an nginx site configuration file to proxy requests to tinykit on localhost:3000, including necessary headers for WebSocket and proxying.

```bash
# Create config
sudo nano /etc/nginx/sites-available/tinykit
```

```nginx
server {
    listen 80;
    server_name app.yourdomain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}
```

```bash
# Enable site
sudo ln -s /etc/nginx/sites-available/tinykit /etc/nginx/sites-enabled/

# Test config
sudo nginx -t

# Reload nginx
sudo systemctl reload nginx

# Add SSL with Certbot
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d app.yourdomain.com
```

--------------------------------

### Run Tinykit with Environment Variables

Source: https://docs.tinykit.studio/docker

Configure the Tinykit container by passing environment variables directly using the -e flag. This is useful for setting API keys, model names, and admin credentials.

```bash
docker run -d \
  -e LLM_PROVIDER=anthropic \
  -e LLM_API_KEY=sk-ant-... \
  -e LLM_MODEL=claude-sonnet-4-20250514 \
  -e POCKETBASE_ADMIN_EMAIL=admin@example.com \
  -e POCKETBASE_ADMIN_PASSWORD=securepassword123 \
  tinykit
```

--------------------------------

### Nginx Authentication with Basic Auth

Source: https://docs.tinykit.studio/security

Protect the /tinykit route using Nginx basic authentication. Ensure you have a .htpasswd file set up.

```nginx
location /tinykit {
  auth_basic "Admin Area";
  auth_basic_user_file /etc/nginx/.htpasswd;
  proxy_pass http://localhost:5173;
}
```

--------------------------------

### Displaying Data with Loading and Empty States

Source: https://docs.tinykit.studio/database

Implement a common pattern for displaying data fetched from the database, including visual indicators for loading states and when no data is available.

```svelte
<script>
  import data from '$data'

  let items = $state([])
  let loading = $state(true)


  data.items.subscribe(records => {
    items = records
    loading = false
  })
</script>

{#if loading}
  <div class="loading">Loading...</div>
{:else if items.length === 0}
  <div class="empty">No items yet</div>
{:else}
  {#each items as item (item.id)}
    <div>{item.name}</div>
  {/each}
{/if}
```

--------------------------------

### Manual Database Backup

Source: https://docs.tinykit.studio/vps

Performs a manual backup of the PocketBase database. Optionally stops the application first for consistency, copies the pb_data directory, and then restarts the application.

```bash
# Stop the app (optional, for consistent backup)
pm2 stop tinykit

# Copy database
cp -r pocketbase/pb_data /backup/tinykit-$(date +%Y%m%d)

# Restart
pm2 start tinykit
```

--------------------------------

### Configure Caddy Reverse Proxy

Source: https://docs.tinykit.studio/vps

Creates and configures the Caddyfile to proxy requests to the tinykit application running on localhost:3000. Supports multiple domains.

```bash
sudo nano /etc/caddy/Caddyfile
```

```caddy
app.yourdomain.com {
    reverse_proxy localhost:3000
}

# Multiple domains for different apps
recipes.yourdomain.com {
    reverse_proxy localhost:3000
}

blog.yourdomain.com {
    reverse_proxy localhost:3000
}
```

```bash
# Reload Caddy
sudo systemctl reload caddy
```

--------------------------------

### Systemd Service Configuration for Tinykit

Source: https://docs.tinykit.studio/vps

Configuration file for a systemd service. Specifies unit dependencies, service type, user, working directory, execution command, restart policy, logging, and environment variables.

```ini
[Unit]
Description=tinykit
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/path/to/tinykit
ExecStart=/path/to/tinykit/deploy/railway/start.sh
Restart=on-failure
RestartSec=10
StandardOutput=syslog
StandardError=syslog
SyslogIdentifier=tinykit
Environment=NODE_ENV=production
Environment=PORT=3000
Environment=HOST=0.0.0.0
Environment=LLM_PROVIDER=anthropic
Environment=LLM_API_KEY=sk-ant-...

[Install]
WantedBy=multi-user.target
```

--------------------------------

### Unknown Domain Redirect Flow

Source: https://docs.tinykit.studio/domain-routing

Illustrates the redirect process when a user accesses a domain that has not been configured with a Tinykit project.

```text
newapp.yourserver.com/
         │
         ▼
    No project found for "newapp.yourserver.com"
         │
         ▼
    Redirect to: /tinykit/new?domain=newapp.yourserver.com
```

--------------------------------

### Combine Data and Content Rendering

Source: https://docs.tinykit.studio/data-fetching

Integrate data fetched from `$data` with content from `$content` to dynamically render pages, articles, and other structured information.

```svelte
<script>
  import data from '$data'
  import content from '$content'

  let recipes = $state([])
  let loading = $state(true)


  data.recipes.subscribe(items => {
    recipes = items
    loading = false
  })

</script>

<h1>{content.page_title}</h1>
<p>{content.page_description}</p>

{#each recipes as recipe (recipe.id)}
  <article>
    <h2>{recipe.title}</h2>
    <p>{recipe.description}</p>
  </article>
{/each}

{#if recipes.length === 0 && !loading}
  <p>{content.empty_state_message}</p>
{/if}
```

--------------------------------

### Fetch Media URLs

Source: https://docs.tinykit.studio/data-fetching

Use `proxy.url()` to generate accessible URLs for remote media files like audio and images, suitable for use in `src` or `href` attributes.

```svelte
<script>
  import { proxy } from '$tinykit'

  let podcast_url = 'https://example.com/episode.mp3'
</script>

<audio src={proxy.url(podcast_url)} controls />
<img src={proxy.url('https://example.com/image.jpg')} alt="Remote image" />
```

--------------------------------

### Import and Subscribe to Data

Source: https://docs.tinykit.studio/database

Import the data module and subscribe to realtime updates for a 'todos' collection. This is useful for displaying and managing dynamic lists of data.

```svelte
<script>
  import data from '$data'

  let todos = $state([])
  let loading = $state(true)

  // Subscribe to realtime updates
  data.todos.subscribe(items => {
    todos = items
    loading = false
  })
</script>
```

--------------------------------

### Set AI Provider to Anthropic

Source: https://docs.tinykit.studio/configuration

Configure the AI provider to use Anthropic's Claude models. This is a recommended setting.

```bash
LLM_PROVIDER=anthropic
```

--------------------------------

### Svelte 5 State Management with Runes

Source: https://docs.tinykit.studio/no-api-key

Demonstrates reactive state, derived values, and side effects using Svelte 5's new rune syntax. Events and props also use rune-based patterns.

```javascript
let count = $state(0)                                      // reactive state
let doubled = $derived(count * 2)                          // simple expressions ONLY
let filtered = $derived.by(() => items.filter(x => x.done)) // use .by() for callbacks/filters
$effect(() => { /* side effects, return cleanup fn */ })
```

--------------------------------

### Docker Compose Configuration for Tinykit

Source: https://docs.tinykit.studio/docker

Define and manage Tinykit services using Docker Compose. This configuration includes building the image, mapping ports, setting environment variables, and defining volumes for data persistence.

```yaml
version: '3.8'

services:
  tinykit:
    build:
      context: .
      dockerfile: deploy/docker/Dockerfile
    ports:
      - "3000:3000"
    environment:
      - LLM_PROVIDER=anthropic
      - LLM_API_KEY=${LLM_API_KEY}
      - LLM_MODEL=claude-sonnet-4-20250514
      - POCKETBASE_ADMIN_EMAIL=admin@example.com
      - POCKETBASE_ADMIN_PASSWORD=${POCKETBASE_ADMIN_PASSWORD}
    volumes:
      - tinykit-data:/app/pocketbase/pb_data
    restart: unless-stopped

volumes:
  tinykit-data:
```

--------------------------------

### Fetch Text Content (RSS, HTML, XML)

Source: https://docs.tinykit.studio/data-fetching

Use `proxy.text()` to fetch and display plain text content from external URLs like RSS feeds.

```svelte
<script>
  import { proxy } from '$tinykit'

  let rss_content = $state('')

  $effect(() => {
    load_rss()
  })

  async function load_rss() {
    rss_content = await proxy.text('https://hnrss.org/frontpage')
  }
</script>
```

--------------------------------

### Cron Job for Daily Backups

Source: https://docs.tinykit.studio/security

Schedule the backup script to run daily at 2 AM using cron.

```bash
# Run daily at 2am
0 2 * * * /path/to/backup.sh
```

--------------------------------

### Persist Tinykit Data with Named Volume

Source: https://docs.tinykit.studio/docker

Use a named volume for the /app/pocketbase/pb_data directory to ensure database persistence across container restarts. This is the recommended method for data management.

```bash
docker run -d \
  -v tinykit-data:/app/pocketbase/pb_data \
  tinykit
```

--------------------------------

### PM2 Management Commands

Source: https://docs.tinykit.studio/vps

Common commands for managing tinykit processes with PM2, including viewing status, logs, restarting, stopping, and deleting processes.

```bash
pm2 status           # View status
pm2 logs tinykit     # View logs
pm2 restart tinykit  # Restart
pm2 stop tinykit     # Stop
pm2 delete tinykit   # Remove from PM2
```

--------------------------------

### Tinykit Server URL Structure

Source: https://docs.tinykit.studio/architecture

This outlines the primary URL paths and their corresponding functions within a Tinykit server instance. It helps understand how different parts of the platform are accessed.

```text
tinykit Server (Railway)
├── /tinykit/dashboard  → Project list (you)
├── /tinykit/studio     → Edit current domain's app (you)
├── /                   → Your generated app (users)
├── /api/agent          → AI endpoints
├── /api/projects       → Project operations
└── /_pb/_              → PocketBase admin
```

--------------------------------

### Set AI Provider API Key

Source: https://docs.tinykit.studio/configuration

Provide your API key for the selected AI provider. Ensure this key is kept secure and not committed to version control.

```bash
LLM_API_KEY=sk-ant-api03-...
```

--------------------------------

### Accessing Specific App Builder by ID

Source: https://docs.tinykit.studio/domain-routing

Jump directly to the builder for a specific app using its ID, regardless of the current domain.

```text
recipes.yourserver.com/tinykit/studio?id=abc123
```

--------------------------------

### Implementing loading state

Source: https://docs.tinykit.studio/no-api-key

Always initialize a loading state variable to true and set it to false within the subscribe callback.

```javascript
let loading = $state(true)
```

--------------------------------

### Create Collection via Code

Source: https://docs.tinykit.studio/database

Create a new collection by adding the first record if the collection does not already exist. The schema is inferred from the record's fields.

```javascript
// Creates 'notes' collection with inferred schema
await data.notes.create({
  title: 'First Note',
  content: 'Hello world',
  created_at: new Date().toISOString()
})
```

--------------------------------

### Raw Fetch Request

Source: https://docs.tinykit.studio/data-fetching

Use the `proxy()` function directly for advanced control over HTTP requests, allowing you to process responses like JSON.

```javascript
import { proxy } from '$tinykit'

const response = await proxy('https://api.example.com/data')
const json = await response.json()
```

--------------------------------

### Update Tinykit Docker Deployment

Source: https://docs.tinykit.studio/docker

Steps to update a Tinykit Docker deployment. This involves pulling the latest code from the repository and rebuilding the Docker image.

```bash
# Pull latest code
git pull

# Rebuild image
docker build -f deploy/docker/Dockerfile -t tinykit .
```

--------------------------------

### Set Server Port

Source: https://docs.tinykit.studio/configuration

Configure the port the server listens on. The default is 3000 for production and 5173 for development. Platforms like Railway may set this automatically.

```bash
PORT=3000
```

--------------------------------

### Using Text Fields for Titles and Labels

Source: https://docs.tinykit.studio/content-fields

Display single-line text content fields for elements like page titles and button labels. These are suitable for short, concise pieces of text.

```svelte
<h1>{content.page_title}</h1>
<button>{content.submit_button}</button>
```

--------------------------------

### Check System Memory Usage

Source: https://docs.tinykit.studio/vps

Commands to check current memory usage on the system. 'free -h' provides a human-readable overview, while 'htop' offers an interactive process viewer.

```bash
free -h
htop
```

--------------------------------

### Create Todo Item with Form Submission

Source: https://docs.tinykit.studio/database

Handles form submission to create a new todo item. It includes state management for the input value and a loading indicator during the save operation.

```svelte
<script>
  import data from '$data'

  let title = $state('')
  let saving = $state(false)

  async function add_todo() {
    if (!title.trim() || saving) return

    saving = true
    try {
      await data.todos.create({
        title: title.trim(),
        completed: false,
        created: new Date().toISOString()
      })
      title = ''
    } finally {
      saving = false
    }
  }
</script>

<form onsubmit={(e) => { e.preventDefault(); add_todo() }}>
  <input bind:value={title} placeholder="New todo" />
  <button disabled={saving}>
    {saving ? 'Adding...' : 'Add'}
  </button>
</form>
```
Tokens:
Raw