From ef0c76e2ffffa0dec2500e29b36aa87f34d8e113 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ferdinand=20M=C3=BCtsch?= Date: Sat, 30 Jan 2021 12:46:13 +0100 Subject: [PATCH] docs: beautify readme --- README.md | 271 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 203 insertions(+), 68 deletions(-) diff --git a/README.md b/README.md index a642aa8..01529fe 100644 --- a/README.md +++ b/README.md @@ -1,70 +1,157 @@ -# πŸ“ˆ wakapi +

πŸ“Š Wakapi

-![](https://badges.fw-web.space/github/license/muety/wakapi) -![GitHub release (latest by date)](https://badges.fw-web.space/github/v/release/muety/wakapi) -![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/muety/wakapi) -![Docker Cloud Build Status](https://badges.fw-web.space/docker/cloud/build/n1try/wakapi) -![GitHub issues](https://img.shields.io/github/issues/muety/wakapi) -![GitHub last commit](https://img.shields.io/github/last-commit/muety/wakapi) -[![Say thanks](https://badges.fw-web.space/badge/SayThanks.io-%E2%98%BC-1EAEDB.svg)](https://saythanks.io/to/n1try) -[![](https://badges.fw-web.space/liberapay/receives/muety.svg?logo=liberapay)](https://liberapay.com/muety/) -![GitHub go.mod Go version](https://badges.fw-web.space/github/go-mod/go-version/muety/wakapi) -[![Go Report Card](https://goreportcard.com/badge/github.com/muety/wakapi)](https://goreportcard.com/report/github.com/muety/wakapi) -![Coding Activity](https://badges.fw-web.space/endpoint?url=https://wakapi.dev/api/compat/shields/v1/n1try/interval:any/project:wakapi&color=blue) -[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=muety_wakapi&metric=security_rating)](https://sonarcloud.io/dashboard?id=muety_wakapi) -[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=muety_wakapi&metric=sqale_rating)](https://sonarcloud.io/dashboard?id=muety_wakapi) -[![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=muety_wakapi&metric=sqale_index)](https://sonarcloud.io/dashboard?id=muety_wakapi) -[![Lines of Code](https://sonarcloud.io/api/project_badges/measure?project=muety_wakapi&metric=ncloc)](https://sonarcloud.io/dashboard?id=muety_wakapi) ---- +

+ + + + +

-**A minimalist, self-hosted WakaTime-compatible backend for coding statistics** +

+ + + + + +

-![Wakapi screenshot](https://anchr.io/i/bxQ69.png) +

A minimalist, self-hosted WakaTime-compatible backend for coding statistics.

+ +
+

+ + Website + + | + + Features + + | + + How to use + + | + + Issues + + | + + Contact + +

+
+ +

+ +

+ +## Table of Contents +* [User Survey](#-user-survey) +* [Features](#-features) +* [How to use](#-how-to-use) +* [Configuration Options](#-configuration-options) +* [API Endpoints](#-api-endpoints) +* [Prometheus Export](#-prometheus-export) +* [Best Practices](#-best-practices) +* [Developer Notes](#-developer-notes) +* [Support](#-support) +* [FAQs](#-faqs) ## πŸ“¬ **User Survey** I'd love to get some community feedback from active Wakapi users. If you want, please participate in the recent [user survey](https://github.com/muety/wakapi/issues/82). Thanks a lot! -## πŸ‘€ Demo -πŸ”₯ **New:** Wakapi is available as a hosted service now. Check out **[wakapi.dev](https://wakapi.dev)**. Please use responsibly. +## πŸš€ Features +* βœ… 100 % free and open-source +* βœ… Built by developers for developers +* βœ… Statistics for projects, languages, editors, hosts and operating systems +* βœ… Badges +* βœ… REST API +* βœ… Partially compatible with WakaTime +* βœ… WakaTime relay to use both +* βœ… Support for [Prometheus](https://github.com/muety/wakapi#%EF%B8%8F-prometheus-export) exports +* βœ… Self-hosted -To use the hosted version set `api_url = https://wakapi.dev/api/heartbeat`. However, we do not guarantee data persistence, so you might potentially lose your data if the service is taken down some day ❕ +## ⌨️ How to use? +There are different options for how to use Wakapi, ranging from out hosted cloud service to self-hosting it. Regardless of which option choose, you will always have to do the [client setup](#-client-setup) in addition. -## βš™οΈ Prerequisites -**On the server side:** +### ☁️ Option 1: Use [wakapi.dev](https://wakapi.dev) +If you want to you out free, hosted cloud service, all you need to do is create an account and the set up your client-side tooling (see below). + +However, we do not guarantee data persistence, so you might potentially lose your data if the service is taken down some day ❕ + +### 🐳 Option 2: Use Docker +```bash +# Create a persistent volume +$ docker volume create wakapi-data + +# Run the container +$ docker run -d \ + -p 3000:3000 \ + -e "WAKAPI_PASSWORD_SALT=$(cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w ${1:-32} | head -n 1)" \ + -v wakapi-data:/data \ + --name wakapi n1try/wakapi +``` + +**Note:** By default, SQLite is used as a database. To run Wakapi in Docker with MySQL or Postgres, see [Dockerfile](https://github.com/muety/wakapi/blob/master/Dockerfile) and [config.default.yml](https://github.com/muety/wakapi/blob/master/config.default.yml) for further options. + +### πŸ“¦ Option 3: Run a release +```bash +# Download the release and unpack it +$ wget https://github.com/muety/wakapi/releases/download/1.20.2/wakapi_linux_amd64.zip +$ unzip wakapi_linux_amd64.zip + +# Optionally adapt config to your needs +$ vi config.yml + +# Run it +$ ./ wakapi +``` + +### πŸ§‘β€πŸ’» Option 4: Run from source +#### Prerequisites * Go >= 1.13 (with `$GOPATH` properly set) * gcc (to compile [go-sqlite3](https://github.com/mattn/go-sqlite3)) * Fedora / RHEL: `dnf install @development-tools` * Ubuntu / Debian: `apt install build-essential` * Windows: See [here](https://github.com/mattn/go-sqlite3/issues/214#issuecomment-253216476) -* _Optional_: One of the [supported databases](#supported-databases) -**On your local machine:** -* [WakaTime plugin](https://wakatime.com/plugins) for your editor / IDE - -## ⌨️ Server Setup -### Run from source -1. Copy `config.default.yml` to `config.yml` and adapt it to your needs -1. Install packaging tool: `GO111MODULE=on go get github.com/markbates/pkger/cmd/pkger` -1. Build executable: `GO111MODULE=on go generate && go build -o wakapi` -1. Run server: `./wakapi` - -**As an alternative** to building from source you can also grab a pre-built [release](https://github.com/muety/wakapi/releases). Steps 2, 3 and 5 apply analogously. - -**Note:** By default, the application is running in dev mode. However, it is recommended to set `ENV=production` for enhanced performance and security. To still be able to log in when using production mode, you either have to run Wakapi behind a reverse proxy, that enables for HTTPS encryption (see [best practices](#best-practices)) or set `security.insecure_cookies` to `true` in `config.yml`. - -### Run with Docker +#### Compile & Run ```bash -docker run -d -p 3000:3000 -e "WAKAPI_PASSWORD_SALT=$(cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w ${1:-32} | head -n 1)" --name wakapi n1try/wakapi +# Adapt config to your needs +$ cp config.default.yml config.yml +$ vi config.yml + +# Install packaging tool +$ export GO111MODULE=on +$ go get github.com/markbates/pkger/cmd/pkger + +# Build the executable +$ go generate +$ go build -o wakapi + +# Run it +$ ./wakapi ``` -By default, SQLite is used as a database. To run Wakapi in Docker with MySQL or Postgres, see [Dockerfile](https://github.com/muety/wakapi/blob/master/Dockerfile) and [config.default.yml](https://github.com/muety/wakapi/blob/master/config.default.yml) for further options. +**Note:** By default, the application is running in dev mode. However, it is recommended to set `ENV=production` for enhanced performance and security. To still be able to log in when using production mode, you either have to run Wakapi behind a reverse proxy, that enables for HTTPS encryption (see [best practices](#best-practices)) or set `security.insecure_cookies = true` in `config.yml`. -### Running tests -```bash -CGO_FLAGS="-g -O2 -Wno-return-local-addr" go test -json -coverprofile=coverage/coverage.out ./... -run ./... +### πŸ’» Client Setup +Wakapi relies on the open-source [WakaTime](https://github.com/wakatime/wakatime) client tools. In order to collect statistics to Wakapi, you need to set them up. + +1. **Set up WakaTime** for your specific IDE or editor. Please refer to the respective [plugin guide](https://wakatime.com/plugins) +2. **Editing your local `~/.wakatime.cfg`** file as follows + +``` +# Your Wakapi server URL or 'https://wakapi.dev/api/heartbeat' when using the cloud server +api_url = http://localhost:3000/api/heartbeat + +# Your Wakapi API key (get it from the web interface after having created an account) +api_key = 406fe41f-6d69-4183-a4cc-121e0c524c2b ``` -## πŸ”§ Configuration +Optionally, you can set up a [client-side proxy](docs/advanced_setup.md) in addition. + +## πŸ”§ Configuration Options You can specify configuration options either via a config file (default: `config.yml`, customziable through the `-c` argument) or via environment variables. Here is an overview of all options. | YAML Key | Environment Variable | Default | Description | @@ -97,23 +184,7 @@ Wakapi uses [GORM](https://gorm.io) as an ORM. As a consequence, a set of differ * [Postgres](https://hub.docker.com/_/postgres) (_open-source as well_) * [CockroachDB](https://www.cockroachlabs.com/docs/stable/install-cockroachdb-linux.html) (_cloud-native, distributed, Postgres-compatible API_) -### Optional: WakaTime relay -You can connect Wakapi with WakaTime in a way that all heartbeats sent to Wakapi are relayed. This way, you can use both services at the same time. Go to the settings page of your instance to configure this integration. - -## πŸ’» Client Setup -Wakapi relies on the open-source [WakaTime](https://github.com/wakatime/wakatime) client tools. In order to collect statistics to Wakapi, you need to set them up. - -1. **Set up WakaTime** for your specific IDE or editor. Please refer to the respective [plugin guide](https://wakatime.com/plugins) -2. Make your local WakaTime client talk to Wakapi by **editing your local `~/.wakatime.cfg`** file as follows - -``` -api_url = http://localhost:3000/api/heartbeat # <- insert your server here -api_key = 406fe41f-6d69-4183-a4cc-121e0c524c2b # <- insert your api key here -``` - -You can view your API Key after logging in to the web interface. - -### Optional: Client-side proxy +### Client-side proxy (`optional`) See the [advanced setup instructions](docs/advanced_setup.md). ## πŸ”§ API Endpoints @@ -135,18 +206,82 @@ It is a standalone webserver that connects to your Wakapi instance and exposes t Simply configure the exporter with `WAKA_SCRAPE_URI` to equal `"https://wakapi.your-server.com/api/compat/wakatime/v1"` and set your API key accordingly. -## 🏷 Badges -We recently introduced support for [Shields.io](https://shields.io) badges (see above). Visit your Wakapi server's settings page to see details. - ## πŸ‘ Best Practices It is recommended to use wakapi behind a **reverse proxy**, like [Caddy](https://caddyserver.com) or _nginx_ to enable **TLS encryption** (HTTPS). However, if you want to expose your wakapi instance to the public anyway, you need to set `server.listen_ipv4` to `0.0.0.0` in `config.yml` +## πŸ€“ Developer Notes +### Running tests +```bash +CGO_FLAGS="-g -O2 -Wno-return-local-addr" go test -json -coverprofile=coverage/coverage.out ./... -run ./... +``` + ## πŸ™ Support If you like this project, please consider supporting it πŸ™‚. You can donate either through [buying me a coffee](https://buymeacoff.ee/n1try) or becoming a GitHub sponsor. Every little donation is highly appreciated and boosts the developers' motivation to keep improving Wakapi! -## ⚠️ Important Note -**This is not an alternative to using WakaTime.** It is just a custom, non-commercial, self-hosted application to collect coding statistics using the already existing editor plugins provided by the WakaTime community. It was created for personal use only and with the purpose of keeping the sovereignity of your own data. However, if you like the official product, **please support the authors and buy an official WakaTime subscription!** +## ❔ FAQs +Since Wakapi heavily relies on the concepts provided by WakaTime, [their FAQs](https://wakatime.com/faq) apply to Wakapi for large parts as well. You might find answers there. + +
+What data is sent to Wakapi? +
  • File names
    • +
  • Project names
    • +
  • Editor names
    • +
  • You computer's host name
    • +
  • Timestamps for every action you take in your editor
    • +
  • ...
    • + +See the related [WakaTime FAQ section](https://wakatime.com/faq#data-collected) for details. + +If you host Wakapi yourself, you have control over all your data. However, if you use our webservice and are concerned about privacy, you can also [exclude or obfuscate](https://wakatime.com/faq#exclude-paths) certain file- or project names. +
    + +
    +What happens if I'm offline? +All data is cached locally on your machine and sent in batches once you're online again. +
    + +
    +How did Wakapi come about? +Wakapi was started when I was a student, who wanted to track detailed statistics about my coding time. Although I'm a big fan of WakaTime I didn't want to pay 9 $ a month back then. Luckily, most parts of WakaTime are open source! +
    + +
    +How does Wakapi compare to WakaTime? +Wakapi is a small subset of WakaTime and has a lot less features. Cool WakaTime features, that are missing Wakapi, include: +
  • Leaderboards
    • +
  • Embeddable Charts
    • +
  • Personal Goals
    • +
  • Team- / Organization Support
    • +
  • Integrations (with GitLab, etc.)
    • +
  • Richer API
    • + +WakaTime is worth the price. However, if you only want basic statistics and keep sovereignty over your data, you might want to go with Wakapi. +
    + +
    +How are durations calculated? +Inferring a measure for your coding time from heartbeats works a bit different than in WakaTime. While WakaTime has timeout intervals, Wakapi essentially just pads every heartbeat, that occurs after a longer pause, with 2 extra minutes. + +Here is an example (circles are heartbeats): + +``` +|---o---o--------------o---o---| +| |10s| 3m |10s| | + +``` + +It is unclear how to handle the three minutes in between. Did the developer do a 3-minute break or were just no heartbeats being sent, e.g. because the developer was starring at the screen find a solution, but not actually typing code. + +
  • WakaTime (with 5 min timeout): 3 min 20 sec +
  • WakaTime (with 2 min timeout): 20 sec +
  • Wakapi: 10 sec + 2 min + 10 sec = 2 min 20 sec
    • + +Wakapi adds a "padding" of two minutes before the third heartbeat. This is why total times will slightly vary between Wakapi and WakaTime. +
    + +## πŸ™ Thanks +I highly appreciate the efforts of [@alanhamlett](https://github.com/alanhamlett) and the WakaTime team and am thankful for their software being open source. ## πŸ““ License GPL-v3 @ [Ferdinand MΓΌtsch](https://muetsch.io)