diff --git a/README.md b/README.md index a642aa8..01529fe 100644 --- a/README.md +++ b/README.md @@ -1,70 +1,157 @@ -# π wakapi +
+ +
+ +## 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. + +