Dashicy

🚀 Quick Start: Dev Server

The fastest way to explore Dashica's Go API and widget examples:

# 1. Start ClickHouse with sample data
docker-compose -f docker-compose.dev.yml up -d

# 2. Build frontend assets
npm install  # Only needed once
npm run build

# 3. Set up and run the dev server
cd docs/dev-server
cp dashica_config.example.yaml dashica_config.yaml
go run main.go

# 4. Open http://127.0.0.1:8080/docs/intro

The dev server includes:

• 📚 Complete documentation and API reference
• 🎨 Interactive widget examples (coming soon)
• 🗄️ Pre-loaded sample data in ClickHouse
• 🔄 Ready-to-use development environment

See docs/dev-server/README.md for details.

---

Development

Development Setup

Prerequisites:

• Docker Compose

Get started:

# at root of repo:
dev setup

# follow instructions

Running Tests

# run all unit tests
dev tests_run_all

The test setup is a bit intricate, as shown by the image below:

• The main idea is to base the tests on real incidents. For data privacy reasons, we only extract the event timestamps from the incident and not the event payload. This usually is enough because alerts normally are based on counting events in a timeframe.
• there exists tooling for downloading incident data from prod - described at http://127.0.0.1:8080/content/__testing/test-data (which is the rendered version of test-data.md). This is ALSO used for visualizing the shape and volume of the data - extremely helpful for writing and debugging tests.

┌──────────────────────────────────┐                                                                                                           
│          E2E testcases           │───────────────────────────────┐                                                                           
└──────────────────────────────────┘                      load and │                                                                           
                  │use                                     execute ▼                                                                           
                  ▼                              ┌──────────────────────────────────┐                                                          
┌──────────────────────────────────┐             │    alerts.yaml + SQL queries     │                                    _____ ___ ___ _____   
│   dashica_config_testing.yaml    │             │  server/alerting/test_fixtures/  │─ ─ ─ ┐ builds on fixture          |_   _| __/ __|_   _|  
└──────────────────────────────────┘             └──────────────────────────────────┘        data for the                 | | | _|\__ \ | |    
                  │default: use                                                            │ different testcases          |_| |___|___/ |_|    
                  │the local DB                                                            ▼                                                   
                  ▼                                                ┌───────────────────────────────────────────────┐                           
┌──────────────────────────────────┐          imported via         │                   FIXTURES                    │                           
│            CLICKHOUSE            │  /docker_entrypoint_initdb.d  │deployment/local_dev/clickhouse/test_prod_dumps│                           
│        docker-compose.yml        │◀──────────────────────────────│                  /*.parquet                   ╠═════════════════════════
└──────────────────────────────────┘                               │  contains event timestamps of real incidents  │                           
                  ▲                                                └───────────────────────────────────────────────┘       ___  _____   __     
                  │ alert_target:                                                          ▲                              |   \| __\ \ / /     
                  │ use the local DB                                              visualize│                              | |) | _| \ V /      
┌──────────────────────────────────┐                         ┌──────────────────────────────────────────────────────────┐ |___/|___| \_/       
│       dashica_config.yaml        │                         │     Dev Dashboard for visualizing the fixtures (with     │                      
└──────────────────────────────────┘                         │  explanations); helpful for test creation and debugging  │                      
                                                             │    http://127.0.0.1:8080/content/__testing/test-data     │                      
                                                             └──────────────────────────────────────────────────────────┘                      

Development Cookbook / Tips and Tricks

In this section, we collect various tips and tricks for specific situations.

Starting from Scratch again / dropping all data in the container

# remove all containers; reset database state
docker compose down -v -t0

# remove all untracked files (dry run - does NOT delete anything)
git clean -X -n
# remove all untracked files
git clean -X -f

Goreleaser Debugging

cd server
goreleaser release --snapshot --clean  --verbose

docker run --rm --name dashica-dev -it --entrypoint /bin/bash ghcr.io/sandstorm/dashica:latest-arm64

docker run --rm -it ghcr.io/sandstorm/dashica:latest-arm64

Thanks to

ESBuild - we copied their go/node.js binary build setup + distribution through NPM and adjusted that.