keepercheky

KeeperCheky Development Guide

Estado Actual: v1.0.0-dev.17 - Desarrollo activo con la mayoría de features implementadas

🚀 Quick Start

✅ What’s Implemented

Backend Services (Go)

Service Integrations

Frontend (Alpine.js + Tailwind)

API Endpoints

Features

Prerequisites

First-Time Setup

  1. Clone the repository 
    git clone https://github.com/carcheky/keepercheky.git
cd keepercheky
  2. Initialize development environment 
    make init
  3. Start development server 
    make dev
  4. Access the application
    • Open http://localhost:8000
    • You should see the KeeperCheky dashboard

🛠️ Development Workflow

The development environment uses Air for automatic hot-reload:

# Start with hot-reload



make dev

# The server will automatically restart when you edit:



# - Go files (*.go)



# - Templates (*.html)



# - Config files (*.yaml)

Using Docker Compose Watch (Docker 28+)

Docker 28+ includes a watch feature that syncs file changes:

# Start with compose watch



make dev-watch

What gets synced:

Useful Commands

# View logs



make logs

# Open shell in container



make shell

# Run tests



make test

# Format code



make fmt

# Stop server



make stop

# Clean everything



make clean

📁 Project Structure

keepercheky/
├── cmd/
│   └── server/
│       └── main.go              # Application entry point
├── internal/                     # Private application code
│   ├── config/                   # Configuration management
│   │   └── config.go
│   ├── models/                   # Database models (GORM)
│   │   └── models.go
│   ├── repository/               # Data access layer
│   │   └── repository.go
│   ├── service/                  # Business logic
│   │   ├── clients/              # External service clients
│   │   ├── cleanup/              # Cleanup strategies
│   │   └── scheduler/            # Job scheduling
│   ├── handler/                  # HTTP handlers (Fiber)
│   │   ├── handler.go
│   │   ├── dashboard.go
│   │   ├── media.go
│   │   └── ...
│   └── middleware/               # HTTP middleware
│       └── middleware.go
├── web/
│   ├── templates/                # Go html/template files
│   │   ├── layouts/
│   │   │   └── main.html
│   │   └── pages/
│   │       ├── dashboard.html
│   │       └── ...
│   └── static/                   # CSS, JS, images
│       ├── css/
│       ├── js/
│       └── images/
├── pkg/                          # Public/shared packages
│   ├── logger/
│   │   └── logger.go
│   └── utils/
├── data/                         # Runtime data (gitignored)
│   └── dev.db                    # SQLite database
├── config/                       # Configuration files
│   └── config.example.yaml
├── .air.toml                     # Air configuration
├── docker-compose.yml        # Development compose file
├── Dockerfile.dev                # Development Dockerfile
├── Makefile                      # Development commands
└── README.md

🔧 Configuration

Environment Variables

The application uses environment variables with the prefix KEEPERCHEKY_:

# App



KEEPERCHEKY_APP_ENVIRONMENT=development
KEEPERCHEKY_APP_LOG_LEVEL=debug
KEEPERCHEKY_APP_DRY_RUN=true
KEEPERCHEKY_APP_LEAVING_SOON_DAYS=7

# Server



KEEPERCHEKY_SERVER_PORT=8000
KEEPERCHEKY_SERVER_HOST=0.0.0.0

# Database



KEEPERCHEKY_DATABASE_TYPE=sqlite
KEEPERCHEKY_DATABASE_PATH=./data/dev.db

Configuration File

Alternatively, create config/config.yaml:

app:
  environment: development
  log_level: debug
  dry_run: true
  leaving_soon_days: 7
  scheduler_enabled: false

server:
  port: "8000"
  host: "0.0.0.0"

database:
  type: sqlite
  path: ./data/dev.db

clients:
  radarr:
    enabled: false
    url: "http://radarr:7878"
    api_key: ""
  
  sonarr:
    enabled: false
    url: "http://sonarr:8989"
    api_key: ""
  
  jellyfin:
    enabled: false
    url: "http://jellyfin:8096"
    api_key: ""
    username: ""
    password: ""

🧪 Testing

Running Tests

# All tests



make test

# With coverage



make test-coverage

# Specific package



go test -v ./internal/service/...

Writing Tests

Follow the standard Go testing conventions:

// internal/repository/repository_test.go
package repository

import (
    "testing"
    "github.com/stretchr/testify/assert"
)

func TestMediaRepository_GetAll(t *testing.T) {
    // Setup
    db := setupTestDB(t)
    defer db.Close()
    
    repo := NewMediaRepository(db)
    
    // Test
    media, err := repo.GetAll()
    
    // Assert
    assert.NoError(t, err)
    assert.NotNil(t, media)
}

🎨 Frontend Development

Alpine.js Components

Create reactive components in templates:

<div x-data="mediaList()" x-init="init()">
    <template x-for="item in media" :key="item.id">
        <div x-text="item.title"></div>
    </template>
</div>

<script>
function mediaList() {
    return {
        media: [],
        
        async init() {
            this.media = await this.fetchMedia();
        },
        
        async fetchMedia() {
            const response = await fetch('/api/media');
            return await response.json();
        }
    }
}
</script>

Tailwind CSS

Use Tailwind utility classes directly in templates:

<div class="bg-white shadow rounded-lg p-6">
    <h2 class="text-2xl font-bold text-gray-900">Title</h2>
</div>

🐛 Debugging

VS Code Debugging

  1. Install the Go extension for VS Code
  2. Set breakpoints in your code
  3. Press F5 to start debugging
  4. Or use the “Launch Package” configuration

Docker Debugging

# View container logs



make logs

# Open shell in container



make shell

# Inside container, you can:



go run ./cmd/server

Common Issues

Port already in use:

# Find and kill process using port 8000



lsof -ti:8000 | xargs kill -9

# Or use a different port



KEEPERCHEKY_SERVER_PORT=8001 make dev

Database locked:

# Stop all containers and clean



make clean
make init
make dev

📚 Additional Resources

🤝 Contributing

  1. Create a new branch: git checkout -b feature/my-feature
  2. Make your changes
  3. Run tests: make test
  4. Format code: make fmt
  5. Commit: git commit -m "feat: add my feature"
  6. Push: git push origin feature/my-feature
  7. Create Pull Request

📝 Coding Guidelines

See .github/copilot-instructions.md for detailed coding standards.

Key principles:

Happy coding! 🚀

If you encounter any issues, check the main documentation or open an issue on GitHub.

This site is open source. Improve this page.