Docs v4 (#1473)

* Tag v3

website/docusaurus.config.js

@@ -68,7 +68,7 @@ const config = {
           lastVersion: 'current',
           versions: {
             current: {
-              label: 'v3',
+              label: 'v4',
               path: '',
             },
           },

website/versioned_docs/version-v3/basics/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Basics",
+  "position": 1
+}

website/versioned_docs/version-v3/basics/configuration.md

@@ -0,0 +1,54 @@
+# Configuration
+## Configuration sources
+
+Settings can be specified in three ways (in order of precedence): 
+
+1. Command line arguments.
+1. Environment variables starting with **`DKRON_`**
+1. **`dkron.yml`** config file
+
+:::caution
+Dkron sends anonymous usage data to a server with the purpose of elaborating usage statistics, if you want to disable statistics collection, you can disable it in the dkron config file or in the command line using `--disable-usage-stats` parameter
+:::
+
+## Config file location
+
+Config file will be loaded from the following paths:
+
+- `/etc/dkron`
+- `$HOME/.dkron`
+- `./config`
+
+### Config file example
+
+```yaml
+# Dkron example configuration file
+# server: false
+# bootstrap-expect: 3
+# data-dir: dkron.data
+# log-level: debug
+# tags:
+#   dc: east
+# encrypt: a-valid-key-generated-with-dkron-keygen
+# retry-join:
+#   - 10.0.0.1
+#   - 10.0.0.2
+#   - 10.0.0.3
+# raft-multiplier: 1
+# webhook-url: https://hooks.slack.com/services/XXXXXX/XXXXXXX/XXXXXXXXXXXXXXXXXXXX
+# webhook-payload: "payload={\"text\": \"{{.Report}}\", \"channel\": \"#foo\"}"
+# webhook-headers: Content-Type:application/x-www-form-urlencoded
+# mail-host: email-smtp.eu-west-1.amazonaws.com
+# mail-port: 25
+# mail-username": mailuser
+# mail-password": mailpassword
+# mail-from": cron@example.com
+# mail-subject_prefix: [Dkron]
+```
+
+### SEE ALSO
+
+* [dkron agent](/docs/cli/dkron_agent/)	 - Start a dkron agent
+* [dkron doc](/docs/cli/dkron_doc/)	 - Generate Markdown documentation for the Dkron CLI.
+* [dkron keygen](/docs/cli/dkron_keygen/)	 - Generates a new encryption key
+* [dkron version](/docs/cli/dkron_version/)	 - Show version

website/versioned_docs/version-v3/basics/getting-started.md

@@ -0,0 +1,97 @@
+---
+sidebar_position: 1
+---
+# Getting started
+
+## Introduction
+
+Dkron nodes can work in two modes, agents or servers.
+
+A Dkron agent is a cluster member that can handle job executions, run your scripts and return the resulting output to the server.
+
+A Dkron server is also a cluster member that send job execution queries to agents or other servers, so servers can execute jobs too.
+
+The main distinction is that servers order job executions, can be used to schedule jobs, handles data storage and participate on leader election.
+
+Dkron clusters have a leader, the leader is responsible of starting job execution queries in the cluster.
+
+Any Dkron agent or server acts as a cluster member and it's available to run scheduled jobs.
+
+Default is for all nodes to execute each job. You can control what nodes run a job by specifying tags and a count of target nodes having this tag. This gives an unprecedented level of flexibility in runnig jobs across a cluster of any size and with any combination of machines you need.
+
+All the execution responses will be gathered by the scheduler and stored in the database.
+
+## State storage
+
+Dkron deployment is just a single binary, it stores the state in an internal BuntDB instance and replicate all changes between all server nodes using the Raft protocol, it doesn't need any other storage system outside itself.
+
+## Installation
+
+See the [installation](installation.md).
+
+## Configuration
+
+See the [configuration](configuration.md).
+
+## Usage
+
+By default Dkron uses the following ports:
+
+- `8946` for serf layer between agents
+- `8080` for HTTP for the API and Dashboard
+- `6868` for gRPC and raft layer comunication between agents.
+
+:::info
+Be sure you have opened this ports (or the ones that you configured) in your firewall or AWS security groups.
+:::
+
+### Starting a single node
+
+Works out of the box, good for non HA installations.
+
+- System service: If no changes are done to the default config files, dkron will start as a service in single mode.
+- Command line: Running a single node with default config can be done by running:
+
+```
+dkron agent --server --bootstrap-expect=1
+```
+
+Check your server is working: `curl localhost:8080/v1`
+
+:::info
+For a full list of configuration parameters and its description, see the [CLI docs](/docs/cli/dkron_agent)
+:::
+
+### Create a Job
+
+:::info
+This job will only run in just one `server` node due to the node count in the tag. Refer to the [target node spec](/docs/usage/target-nodes-spec) for details.
+:::
+
+```bash
+curl localhost:8080/v1/jobs -XPOST -d '{
+  "name": "job1",
+  "schedule": "@every 10s",
+  "timezone": "Europe/Berlin",
+  "owner": "Platform Team",
+  "owner_email": "platform@example.com",
+  "disabled": false,
+  "tags": {
+    "server": "true:1"
+  },
+  "metadata": {
+    "user": "12345"
+  },
+  "concurrency": "allow",
+  "executor": "shell",
+  "executor_config": {
+    "command": "date"
+  }
+}'
+```
+
+For full Job params description refer to the Job model in the [API guide](/api)
+
+That's it!
+
+#### To start configuring an HA installation of Dkron follow the [clustering guide](/docs/usage/clustering)

website/versioned_docs/version-v3/basics/installation.md

@@ -0,0 +1,67 @@
+# Installation
+## Running the binary
+
+Download the packaged archive for your platform from the [downloads page](https://github.com/distribworks/dkron/releases) and extract the package to a shared location in your drive, like /opt/local/bin.
+
+Run Dkron with default setting: `dkron agent --server --bootstrap-expect=1`
+
+Navigate to http://localhost:8080/ui
+
+## Installing the package
+
+### Debian repo
+
+APT repository: 
+```
+deb [trusted=yes] https://repo.distrib.works/apt/ /
+```
+
+Then install: `sudo apt-get install dkron`
+
+### YUM repo
+
+YUM repository:
+
+```
+[dkron]
+name=Dkron Pro Private Repo
+baseurl=https://repo.distrib.works/yum/
+enabled=1
+gpgcheck=0
+```
+
+Then install: `sudo yum install dkron`
+
+This will start Dkron as a system service and the place example configuration file under `/etc/dkron/dkron.yml`
+
+## Running in Docker
+
+Dkron provides an official Docker image via Docker Hub that can be used for deployment on any system running Docker.
+
+### Launching Dkron as a new container
+
+Here’s a quick one-liner to get you off the ground (please note, we recommend further configuration for production deployments below):
+
+```
+docker run -d -p 8080:8080 --name dkron dkron/dkron agent --server --bootstrap-expect=1 --node-name=node1
+```
+
+This will launch a Dkron server on port 8080 by default. You can use `docker logs -f dkron` to follow the rest of the initialization progress. Once the Dkron startup completes you can access the app at localhost:8080
+
+Since Docker containers have their own ports and we just map them to the system ports as needed it’s easy to move Dkron onto a different system port if you wish. For example running Dkron on port 12345:
+
+```
+docker run -d -p 12345:8080 --name dkron dkron/dkron agent --server --bootstrap-expect=1 --node-name=node1
+```
+
+### Mounting a mapped file storage volume
+
+Dkron uses the local filesystem for storing the embedded database to store its own application data and the Raft protocol log. The end result is that your Dkron data will be on disk inside your container and lost if you ever remove the container.
+
+To persist your data outside of the container and make it available for use between container launches we can mount a local path inside our container.
+
+```
+docker run -d -p 8080:8080 -v ~/dkron.data:/dkron.data --name dkron dkron/dkron agent --server --bootstrap-expect=1 --data-dir=/dkron.data
+```
+
+Now when you launch your container we are mounting that folder from our local filesystem into the container.

website/versioned_docs/version-v3/cli/_category_.json

@@ -0,0 +1,3 @@
+{
+  "label": "CLI"
+}

website/versioned_docs/version-v3/cli/dkron.md

@@ -0,0 +1,34 @@
+---
+date: 2022-06-05
+title: "dkron"
+slug: dkron
+url: /cli/dkron/
+---
+## dkron
+
+Open source distributed job scheduling system
+
+### Synopsis
+
+Dkron is a system service that runs scheduled jobs at given intervals or times,
+just like the cron unix service but distributed in several machines in a cluster.
+If a machine fails (the leader), a follower will take over and keep running the scheduled jobs without human intervention.
+
+### Options
+
+```
+      --config string   config file path
+  -h, --help            help for dkron
+```
+
+### SEE ALSO
+
+* [dkron agent](/docs/cli/dkron_agent/)	 - Start a dkron agent
+* [dkron completion](/docs/cli/dkron_completion/)	 - Generate the autocompletion script for the specified shell
+* [dkron doc](/docs/cli/dkron_doc/)	 - Generate Markdown documentation for the Dkron CLI.
+* [dkron keygen](/docs/cli/dkron_keygen/)	 - Generates a new encryption key
+* [dkron leave](/docs/cli/dkron_leave/)	 - Force an agent to leave the cluster
+* [dkron raft](/docs/cli/dkron_raft/)	 - Command to perform some raft operations
+* [dkron version](/docs/cli/dkron_version/)	 - Show version
+
+###### Auto generated by spf13/cobra on 5-Jun-2022

website/versioned_docs/version-v3/cli/dkron_agent.md

@@ -0,0 +1,113 @@
+---
+date: 2022-06-05
+title: "dkron agent"
+slug: dkron_agent
+url: /cli/dkron_agent/
+---
+## dkron agent
+
+Start a dkron agent
+
+### Synopsis
+
+Start a dkron agent that schedules jobs, listens for executions and runs executors.
+It also runs a web UI.
+
+```
+dkron agent [flags]
+```
+
+### Options
+
+```
+      --advertise-addr string           Address used to advertise to other nodes in the cluster. By default,
+                                        the bind address is advertised. The value supports 
+                                        go-sockaddr/template format.
+      --advertise-rpc-port int          Use the value of rpc-port by default
+      --bind-addr string                Specifies which address the agent should bind to for network services, 
+                                        including the internal gossip protocol and RPC mechanism. This should be 
+                                        specified in IP format, and can be used to easily bind all network services 
+                                        to the same address. The value supports go-sockaddr/template format.
+                                         (default "{{ GetPrivateIP }}:8946")
+      --bootstrap-expect int            Provides the number of expected servers in the datacenter. Either this value 
+                                        should not be provided or the value must agree with other servers in the 
+                                        cluster. When provided, Dkron waits until the specified number of servers are 
+                                        available and then bootstraps the cluster. This allows an initial leader to be 
+                                        elected automatically. This flag requires server mode.
+      --cronitor-endpoint string        Cronitor endpoint to call for notifications
+      --data-dir string                 Specifies the directory to use for server-specific data, including the 
+                                        replicated log. By default, this is the top-level data-dir, 
+                                        like [/var/lib/dkron] (default "dkron.data")
+      --datacenter string               Specifies the data center of the local agent. All members of a datacenter 
+                                        should share a local LAN connection. (default "dc1")
+      --disable-usage-stats             Disable sending anonymous usage stats
+      --dog-statsd-addr string          DataDog Agent address
+      --dog-statsd-tags strings         Datadog tags, specified as key:value
+      --enable-prometheus               Enable serving prometheus metrics
+      --encrypt string                  Key for encrypting network traffic. Must be a base64-encoded 16-byte key
+  -h, --help                            help for agent
+      --http-addr string                Address to bind the UI web server to. Only used when server. The value 
+                                        supports go-sockaddr/template format. (default ":8080")
+      --join strings                    An initial agent to join with. This flag can be specified multiple times
+      --log-level string                Log level (debug|info|warn|error|fatal|panic) (default "info")
+      --mail-from string                From email address to use
+      --mail-host string                Mail server host address to use for notifications
+      --mail-password string            Mail server password to use
+      --mail-payload string             Notification mail payload
+      --mail-port uint16                Mail server port
+      --mail-subject-prefix string      Notification mail subject prefix (default "[Dkron]")
+      --mail-username string            Mail server username used for authentication
+      --node-name string                Name of this node. Must be unique in the cluster (default "mariette.local")
+      --pre-webhook-endpoint string     Pre-webhook endpoint to call for notifications
+      --pre-webhook-headers strings     Headers to use when calling the pre-webhook. Can be specified multiple times
+      --pre-webhook-payload string      Body of the POST request to send on pre-webhook call
+      --profile string                  Profile is used to control the timing profiles used (default "lan")
+      --raft-multiplier int             An integer multiplier used by servers to scale key Raft timing parameters.
+                                        Omitting this value or setting it to 0 uses default timing described below. 
+                                        Lower values are used to tighten timing and increase sensitivity while higher 
+                                        values relax timings and reduce sensitivity. Tuning this affects the time it 
+                                        takes to detect leader failures and to perform leader elections, at the expense 
+                                        of requiring more network and CPU resources for better performance. By default, 
+                                        Dkron will use a lower-performance timing that's suitable for minimal Dkron 
+                                        servers, currently equivalent to setting this to a value of 5 (this default 
+                                        may be changed in future versions of Dkron, depending if the target minimum 
+                                        server profile changes). Setting this to a value of 1 will configure Raft to 
+                                        its highest-performance mode is recommended for production Dkron servers. 
+                                        The maximum allowed value is 10. (default 1)
+      --region string                   Specifies the region the Dkron agent is a member of. A region typically maps 
+                                        to a geographic region, for example us, with potentially multiple zones, which 
+                                        map to datacenters such as us-west and us-east (default "global")
+      --retry-interval string           Time to wait between join attempts. (default "30s")
+      --retry-join strings              Address of an agent to join at start time with retries enabled. 
+                                        Can be specified multiple times.
+      --retry-max int                   Maximum number of join attempts. Defaults to 0, which will retry indefinitely.
+      --rpc-port int                    RPC Port used to communicate with clients. Only used when server. 
+                                        The RPC IP Address will be the same as the bind address. (default 6868)
+      --serf-reconnect-timeout string   This is the amount of time to attempt to reconnect to a failed node before 
+                                        giving up and considering it completely gone. In Kubernetes, you might need 
+                                        this to about 5s, because there is no reason to try reconnects for default 
+                                        24h value. Also Raft behaves oddly if node is not reaped and returned with 
+                                        same ID, but different IP.
+                                        Format there: https://golang.org/pkg/time/#ParseDuration (default "24h")
+      --server                          This node is running in server mode
+      --statsd-addr string              Statsd address
+      --tag strings                     Tag can be specified multiple times to attach multiple key/value tag pairs 
+                                        to the given node, specified as key=value
+      --ui                              Enable the web UI on this node. The node must be server. (default true)
+      --webhook-endpoint string         Webhook endpoint to call for notifications
+      --webhook-headers strings         Headers to use when calling the webhook URL. Can be specified multiple times
+      --webhook-payload string          Body of the POST request to send on webhook call
+      --webhook-url string              Webhook url to call for notifications. Deprecated, use webhook-endpoint instead
+```
+
+### Options inherited from parent commands
+
+```
+      --config string   config file path
+```
+
+### SEE ALSO
+
+* [dkron](/docs/cli/dkron/)	 - Open source distributed job scheduling system
+
+###### Auto generated by spf13/cobra on 5-Jun-2022