Skip to content
Klutch.sh Docs

Deploying Ziit

Introduction

Ziit is a self-hosted time tracking and productivity analytics platform designed for developers and knowledge workers. It automatically tracks time spent on different projects, files, and activities, providing detailed insights into your work patterns without requiring manual time entry.

Built as a privacy-respecting alternative to cloud-based time tracking services, Ziit collects data from your development environment through IDE plugins and aggregates it into meaningful reports and visualizations. All your productivity data stays on your own server.

Key highlights of Ziit:

  • Automatic Time Tracking: IDE plugins capture coding activity without manual intervention
  • Project Analytics: See time spent across different projects, languages, and files
  • Privacy Focused: Self-hosted solution keeps your productivity data private
  • Detailed Reports: Daily, weekly, and monthly productivity summaries
  • Language Statistics: Track time spent in different programming languages
  • Editor Integration: Plugins available for VS Code, JetBrains IDEs, and more
  • API Access: Programmatic access to your time tracking data
  • Dashboard Visualization: Beautiful charts and graphs for productivity insights
  • Open Source: Fully auditable and customizable

This guide walks through deploying Ziit on Klutch.sh using Docker, connecting your IDE plugins, and analyzing your coding productivity.

Why Deploy Ziit on Klutch.sh

Deploying Ziit on Klutch.sh provides several advantages for productivity tracking:

Data Privacy: Keep your productivity data on infrastructure you control rather than third-party services.

Always-On Collection: Your Ziit server remains available 24/7 to receive data from all your devices.

HTTPS by Default: Secure API endpoints for transmitting activity data with automatic SSL certificates.

Persistent Storage: Reliable database storage for historical productivity data.

GitHub Integration: Deploy updates automatically when you push configuration changes.

Custom Domains: Use a memorable domain for your productivity dashboard.

Prerequisites

Before deploying Ziit on Klutch.sh, ensure you have:

  • A Klutch.sh account
  • A GitHub account with a repository for your configuration
  • Basic understanding of Docker and containerization
  • An IDE with plugin support (VS Code, JetBrains, etc.)

Understanding Ziit Architecture

Ziit consists of several components:

Backend Server: Receives activity data from plugins, stores it in a database, and generates reports.

Web Dashboard: Visual interface for viewing productivity statistics and configuring settings.

IDE Plugins: Lightweight extensions that track coding activity and send heartbeats to the server.

API: RESTful endpoints for data submission and retrieval.

Preparing Your Repository

Create a GitHub repository for your Ziit deployment.

Repository Structure

ziit-deploy/
├── Dockerfile
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile for Ziit:

FROM node:18-alpine


# Create app directory
WORKDIR /app


# Clone Ziit
RUN apk add --no-cache git \
    && git clone https://github.com/ziit/ziit.git . \
    && rm -rf .git


# Install dependencies
RUN npm ci --only=production


# Build frontend
RUN npm run build


# Set environment variables
ENV NODE_ENV=production
ENV PORT=3000
ENV DATABASE_URL=${DATABASE_URL}
ENV API_KEY=${API_KEY}


# Expose port
EXPOSE 3000


# Start server
CMD ["npm", "start"]

Environment Variables Reference

VariableRequiredDefaultDescription
DATABASE_URLYes-PostgreSQL or SQLite connection string
API_KEYYes-API key for plugin authentication
PORTNo3000Web server port
TIMEZONENoUTCDefault timezone for reports

Deploying Ziit on Klutch.sh

    Generate Your API Key

    Create a secure API key for plugin authentication:

    Terminal window
    openssl rand -hex 32

    Save this key for both server configuration and IDE plugins.

    Push Your Repository to GitHub

    Initialize and push your configuration to GitHub.

    Create a New Project on Klutch.sh

    Navigate to the Klutch.sh dashboard and create a new project named “ziit” or “time-tracking”.

    Create a New App

    Within your project, create a new app and connect your GitHub repository.

    Configure HTTP Traffic

    Set up HTTP traffic for the web dashboard and API:

    • Select HTTP as the traffic type
    • Set the internal port to 3000

    Set Environment Variables

    Configure the following:

    VariableValue
    API_KEYYour generated API key
    DATABASE_URLDatabase connection string
    TIMEZONEYour local timezone (e.g., America/New_York)

    Attach Persistent Volumes

    Add storage for the database:

    Mount PathRecommended SizePurpose
    /app/data5 GBSQLite database and application data

    Deploy Your Application

    Click Deploy to build and start Ziit.

    Access the Dashboard

    Visit https://your-app-name.klutch.sh to access your productivity dashboard.

Configuring IDE Plugins

VS Code Setup

  1. Install the Ziit extension from the VS Code marketplace
  2. Open settings and configure:
    • Server URL: https://your-app-name.klutch.sh
    • API Key: Your generated API key
  3. The plugin will automatically track your coding activity

JetBrains IDE Setup

  1. Install the Ziit plugin from the JetBrains marketplace
  2. Navigate to Settings > Tools > Ziit
  3. Enter your server URL and API key
  4. Enable tracking

Using the Dashboard

Viewing Statistics

The Ziit dashboard provides:

  • Daily coding time summaries
  • Project breakdown charts
  • Language distribution graphs
  • Editor usage statistics
  • Weekly and monthly trends

Generating Reports

Export reports for:

  • Team productivity reviews
  • Client billing
  • Personal productivity analysis
  • Goal tracking

Troubleshooting Common Issues

Plugin Not Sending Data

Solutions:

  • Verify the server URL is correct and accessible
  • Check that the API key matches
  • Review plugin logs for connection errors

Missing Time Entries

Solutions:

  • Ensure the plugin is enabled in your IDE
  • Check that your IDE has internet access
  • Verify server is receiving heartbeats in logs

Additional Resources

Conclusion

Deploying Ziit on Klutch.sh gives you a private, self-hosted productivity tracking solution. With automatic time tracking from your IDE and detailed analytics through the web dashboard, you can gain insights into your coding habits while keeping your data under your control.