Apocapoc API - Self-Hosted Habit Tracker

REST API for habit tracking built with Go. Self-hosted alternative for developers who want control over their data.

Table of Contents

• Features
• Quick Start
  • Docker Compose (Recommended)
  • Binary Installation
• Use Cases
• API Documentation
• Development
• Architecture

Features

• Multiple habit types: Boolean, Counter, Value
• Flexible scheduling: Daily, Weekly, Monthly
• Statistics: Streaks, completion rates, progress tracking
• JWT authentication, rate limiting, optional email verification
• Registration modes: Open or closed
• SQLite database (single file)
• Swagger UI at /api/v1/docs

Quick Start

Using Docker Compose (Recommended)

1. Create a docker-compose.yml file:

services:
  api:
    image: ghcr.io/davidfolch/apocapoc-api:latest
    ports:
      - "8080:8080"
    environment:
      - DB_PATH=/data/apocapoc.db
      - PORT=8080
      - APP_URL=http://localhost:8080
      - JWT_SECRET=YOUR_SECRET_HERE
      - JWT_EXPIRY=1h
      - REFRESH_TOKEN_EXPIRY=7d
      - DEFAULT_TIMEZONE=UTC
      - REGISTRATION_MODE=open
      # Email configuration (optional)
      # - SMTP_HOST=smtp.example.com
      # - SMTP_PORT=587
      # - SMTP_USER=your-email@example.com
      # - SMTP_PASSWORD=your-password
      # - SMTP_FROM=noreply@example.com
      # - SUPPORT_EMAIL=contact@apocapoc.app
      # - SEND_WELCOME_EMAIL=false
    volumes:
      - habit-data:/data
    restart: unless-stopped

volumes:
  habit-data:

2. Important: Replace YOUR_SECRET_HERE with a secure random string for JWT_SECRET

3. Start the service:

docker-compose up -d

API available at http://localhost:8080

Image tags:

• latest: Stable release (recommended)
• 1, 1.0, 1.0.0: Specific versions
• edge: Development build (unstable)

Configuration:

Required:

• JWT_SECRET: Long random string (required)
• DB_PATH: Database path (default: ./data/apocapoc.db)

Application:

• PORT: HTTP port (default: 8080)
• APP_URL: Public URL for email links
• DEFAULT_TIMEZONE: e.g., UTC, Europe/Madrid

Authentication:

• JWT_EXPIRY: e.g., 1h, 24h
• REFRESH_TOKEN_EXPIRY: e.g., 7d, 168h
• REGISTRATION_MODE: open or closed

Email (optional):

• SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD, SMTP_FROM
• SUPPORT_EMAIL: Default contact@apocapoc.app
• SEND_WELCOME_EMAIL: true/false

Without SMTP config, users are auto-verified.

Using the binary

1. Download from GitHub Releases
2. Extract: tar -xzf apocapoc-api_*_linux_amd64.tar.gz
3. Configure: cp .env.example .env (edit as needed)
4. Run: ./apocapoc-api

API available at http://localhost:8080

Note: Linux only (amd64/arm64). Use Docker for other platforms.

Development

Prerequisites: Go 1.23+, SQLite, Docker (optional)

With Docker:

cp docker-compose.example.yml docker-compose.yml
docker-compose up --build

With Go:

cp .env.example .env
go run cmd/api/main.go

API runs on http://localhost:8080

Use Cases

• Build your own web or mobile frontend
• Create custom CLI tools or scripts
• Keep your habit data on your own infrastructure
• Experiment with a small REST API in Go

API Documentation

Access the interactive Swagger UI at http://localhost:8080/api/v1/docs

Includes endpoint reference, schemas, authentication examples, and live testing.

Architecture

This project follows hexagonal (ports & adapters) architecture:

• domain/: Core business logic and entities
• application/: Use cases (commands & queries)
• infrastructure/: External adapters (database, HTTP, etc.)
• shared/: Common utilities and errors

Support

• 📧 Email: contact@apocapoc.app
• 🐛 Issues: GitHub Issues

Keywords

habit-tracker habit-tracking rest-api self-hosted golang api habits productivity docker sqlite hexagonal-architecture clean-architecture habit-tracker-api self-hosted-api personal-analytics privacy open-source

License

MIT