Add documentation of all server configuration options (#666)

* Added documentation of all configuration options. * sort some flags * adjust config docs to current flags Co-authored-by: 6543 <6543@obermui.de> Co-authored-by: Anton Bracke <anton@ju60.de>
2024-05-31 22:58:35 +00:00 · 2022-02-06 21:21:57 +01:00 · 2022-02-06 21:21:57 +01:00 · 5f79739bc0
parent 6bb964921e
commit 5f79739bc0
2 changed files with 440 additions and 16 deletions
--- a/cmd/server/flags.go
+++ b/cmd/server/flags.go
@ -60,17 +60,17 @@ var flags = []cli.Flag{
 		Name:    "server-key",
 		Usage:   "server ssl key path",
 	},
+	&cli.BoolFlag{
+		EnvVars: []string{"WOODPECKER_LETS_ENCRYPT"},
+		Name:    "lets-encrypt",
+		Usage:   "enable let's encrypt",
+	},
 	&cli.StringFlag{
 		EnvVars: []string{"WOODPECKER_GRPC_ADDR"},
 		Name:    "grpc-addr",
 		Usage:   "grpc address",
 		Value:   ":9000",
 	},
-	&cli.BoolFlag{
-		EnvVars: []string{"WOODPECKER_LETS_ENCRYPT"},
-		Name:    "lets-encrypt",
-		Usage:   "enable let's encrypt",
-	},
 	&cli.StringSliceFlag{
 		EnvVars: []string{"WOODPECKER_ADMIN"},
 		Name:    "admin",
@ -130,6 +130,11 @@ var flags = []cli.Flag{
 		Name:    "agent-secret",
 		Usage:   "server-agent shared password",
 	},
+	&cli.DurationFlag{
+		EnvVars: []string{"WOODPECKER_KEEPALIVE_MIN_TIME"},
+		Name:    "keepalive-min-time",
+		Usage:   "server-side enforcement policy on the minimum amount of time a client should wait before sending a keepalive ping.",
+	},
 	&cli.StringFlag{
 		EnvVars: []string{"WOODPECKER_SECRET_ENDPOINT"},
 		Name:    "secret-service",
@ -163,6 +168,12 @@ var flags = []cli.Flag{
 		Usage:   "token to secure prometheus metrics endpoint",
 		Value:   "",
 	},
+	&cli.StringFlag{
+		EnvVars: []string{"WOODPECKER_STATUS_CONTEXT", "WOODPECKER_GITHUB_CONTEXT", "WOODPECKER_GITEA_CONTEXT"},
+		Name:    "status-context",
+		Usage:   "status context prefix",
+		Value:   "ci/woodpecker",
+	},
 	//
 	// resource limit parameters
 	//
@ -199,12 +210,6 @@ var flags = []cli.Flag{
 	//
 	// Github
 	//
-	&cli.StringFlag{
-		EnvVars: []string{"WOODPECKER_STATUS_CONTEXT", "WOODPECKER_GITHUB_CONTEXT", "WOODPECKER_GITEA_CONTEXT"},
-		Name:    "status-context",
-		Usage:   "status context prefix",
-		Value:   "ci/woodpecker",
-	},
 	&cli.BoolFlag{
 		EnvVars: []string{"WOODPECKER_GITHUB"},
 		Name:    "github",
@ -445,11 +450,6 @@ var flags = []cli.Flag{
 		Name:    "coding-skip-verify",
 		Usage:   "coding skip ssl verification",
 	},
-	&cli.DurationFlag{
-		EnvVars: []string{"WOODPECKER_KEEPALIVE_MIN_TIME"},
-		Name:    "keepalive-min-time",
-		Usage:   "server-side enforcement policy on the minimum amount of time a client should wait before sending a keepalive ping.",
-	},
 	//
 	// development flags
 	//
--- a/docs/docs/30-administration/10-server-config.md
+++ b/docs/docs/30-administration/10-server-config.md
@ -71,3 +71,427 @@ services:
      - [...]
 +     - WOODPECKER_DOCKER_CONFIG=/home/user/.docker/config.json
 ```
+
+## All server configuration options
+
+The following list describes all available server configuration options.
+
+### `WOODPECKER_LOG_LEVEL`
+> Default: empty
+
+Configures the logging level. Possible values are `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `panic`, `disabled` and empty.
+
+### `WOODPECKER_DEBUG_PRETTY`
+> Default: `false`
+
+Enable pretty-printed debug output.
+
+### `WOODPECKER_DEBUG_NOCOLOR`
+> Default: `true`
+
+Disable colored debug output.
+
+### `WOODPECKER_HOST`
+> Default: empty
+
+Server fully qualified url of the user-facing hostname.
+
+Example: `WOODPECKER_HOST=http://woodpecker.example.org`
+
+### `WOODPECKER_SERVER_ADDR`
+> Default: `:8000`
+
+Configures the HTTP listener port.
+
+### `WOODPECKER_SERVER_CERT`
+> Default: empty
+
+Path to an SSL certificate used by the server to accept HTTPS requests.
+
+Example: `WOODPECKER_SERVER_CERT=/path/to/cert.pem`
+
+### `WOODPECKER_SERVER_KEY`
+> Default: empty
+
+Path to an SSL certificate key used by the server to accept HTTPS requests.
+
+Example: `WOODPECKER_SERVER_KEY=/path/to/key.pem`
+
+### `WOODPECKER_LETS_ENCRYPT`
+> Default: `false`
+
+Automatically generates an SSL certificate using Let's Encrypt, and configures the server to accept HTTPS requests.
+
+### `WOODPECKER_GRPC_ADDR`
+> Default: `:9000`
+
+Configures the gRPC listener port.
+
+
+### `WOODPECKER_ADMIN`
+> Default: empty
+
+Comma-separated list of admin accounts.
+
+Example: `WOODPECKER_ADMIN=user1,user2`
+
+### `WOODPECKER_ORGS`
+> Default: empty
+
+Comma-separated list of approved organizations.
+
+Example: `org1,org2`
+
+### `WOODPECKER_REPO_OWNERS`
+> Default: empty
+
+Comma-separated list of syncable repo owners. ???
+
+Example: `user1,user2`
+
+### `WOODPECKER_OPEN`
+> Default: `false`
+
+Enable to allow user registration.
+
+### `WOODPECKER_DOCS`
+> Default: `https://woodpecker-ci.org/`
+
+Link to documentation in the UI.
+
+### `WOODPECKER_SESSION_EXPIRES`
+> Default: `72h`
+
+Configures the session expiration time.
+
+### `WOODPECKER_ESCALATE`
+> Default: `plugins/docker,plugins/gcr,plugins/ecr,woodpeckerci/plugin-docker,woodpeckerci/plugin-docker-buildx`
+
+Docker images to run in privileged mode. Only change if you are sure what you do!
+
+### `WOODPECKER_VOLUME`
+> Default: empty
+
+Comma-separated list of Docker volumes that are mounted into every pipeline step.
+
+Example: `WOODPECKER_VOLUME=/path/on/host:/path/in/container:rw`|
+
+### `WOODPECKER_DOCKER_CONFIG`
+> Default: empty
+
+Configures a specific private registry config for all pipelines.
+
+Example: `WOODPECKER_DOCKER_CONFIG=/home/user/.docker/config.json`
+
+### `WOODPECKER_ENVIRONMENT`
+> Default: empty
+
+TODO
+
+### `WOODPECKER_NETWORK`
+> Default: empty
+
+Comma-separated list of Docker networks that are attached to every pipeline step.
+
+Example: `WOODPECKER_NETWORK=network1,network2`
+
+### `WOODPECKER_AGENT_SECRET`
+> Default: empty
+
+A shared secret used by server and agents to authenticate communication. A secret can be generated by `openssl rand -hex 32`.
+
+### `WOODPECKER_KEEPALIVE_MIN_TIME`
+> Default: empty
+
+Server-side enforcement policy on the minimum amount of time a client should wait before sending a keepalive ping.
+
+Example: `WOODPECKER_KEEPALIVE_MIN_TIME=10s`
+
+### `WOODPECKER_DATABASE_DRIVER`
+> Default: `sqlite3`
+
+The database driver name. Possible values are `sqlite3`, `mysql` or `postgres`.
+
+### `WOODPECKER_DATABASE_DATASOURCE`
+> Default: `woodpecker.sqlite`
+
+The database connection string. The default value is the path of the embedded sqlite database file.
+
+Example:
+```bash
+# MySQL
+# https://github.com/go-sql-driver/mysql#dsn-data-source-name
+WOODPECKER_DATABASE_DATASOURCE=root:password@tcp(1.2.3.4:3306)/woodpecker?parseTime=true
+
+# PostgreSQL
+# https://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-CONNSTRING
+WOODPECKER_DATABASE_DATASOURCE=postgres://root:password@1.2.3.4:5432/woodpecker?sslmode=disable
+```
+
+### `WOODPECKER_PROMETHEUS_AUTH_TOKEN`
+> Default: empty
+
+Token to secure the Prometheus metrics endpoint.
+
+### `WOODPECKER_STATUS_CONTEXT`
+> Default: `ci/woodpecker`
+
+Context prefix Woodpecker will use to publish status messages to SCM. You probably will only need to change it if you run multiple Woodpecker instances for a single repository.
+
+---
+
+### `WOODPECKER_LIMIT_MEM_SWAP`
+> Default: `0`
+
+The maximum amount of memory a single pipeline container is allowed to swap to disk, configured in bytes. There is no limit if `0`.
+
+### `WOODPECKER_LIMIT_MEM`
+> Default: `0`
+
+The maximum amount of memory a single pipeline container can use, configured in bytes. There is no limit if `0`.
+
+### `WOODPECKER_LIMIT_SHM_SIZE`
+> Default: `0`
+
+The maximum amount of memory of `/dev/shm` allowed in bytes. There is no limit if `0`.
+
+### `WOODPECKER_LIMIT_CPU_QUOTA`
+> Default: `0`
+
+The number of microseconds per CPU period that the container is limited to before throttled. There is no limit if `0`.
+
+### `WOODPECKER_LIMIT_CPU_SHARES`
+> Default: `0`
+
+The relative weight vs. other containers.
+
+### `WOODPECKER_LIMIT_CPU_SET`
+> Default: empty
+
+Comma-separated list to limit the specific CPUs or cores a pipeline container can use.
+
+Example: `WOODPECKER_LIMIT_CPU_SET=1,2`
+
+---
+
+### `WOODPECKER_GITHUB`
+> Default: `false`
+
+Enables the GitHub driver.
+
+### `WOODPECKER_GITHUB_URL`
+> Default: `https://github.com`
+
+Configures the GitHub server address.
+
+### `WOODPECKER_GITHUB_CLIENT`
+> Default: empty
+
+Configures the GitHub OAuth client id. This is used to authorize access.
+
+### `WOODPECKER_GITHUB_SECRET`
+> Default: empty
+
+Configures the GitHub OAuth client secret. This is used to authorize access.
+
+### `WOODPECKER_GITHUB_MERGE_REF`
+> Default: `true`
+
+TODO
+
+### `WOODPECKER_GITHUB_SKIP_VERIFY`
+> Default: `false`
+
+Configure if SSL verification should be skipped.
+
+---
+
+### `WOODPECKER_GOGS`
+> Default: `false`
+
+Enables the Gogs driver.
+
+### `WOODPECKER_GOGS_URL`
+> Default: `https://github.com`
+
+Configures the Gogs server address.
+
+### `WOODPECKER_GOGS_GIT_USERNAME`
+> Default: empty
+
+This username is used to authenticate and clone all private repositories.
+
+### `WOODPECKER_GOGS_GIT_PASSWORD`
+> Default: empty
+
+The password is used to authenticate and clone all private repositories.
+
+### `WOODPECKER_GOGS_PRIVATE_MODE`
+> Default: `false`
+
+TODO
+
+### `WOODPECKER_GOGS_SKIP_VERIFY`
+> Default: `false`
+
+Configure if SSL verification should be skipped.
+
+---
+
+### `WOODPECKER_GITEA`
+> Default: `false`
+
+Enables the Gitea driver.
+
+### `WOODPECKER_GITEA_URL`
+> Default: `https://try.gitea.io`
+
+Configures the Gitea server address.
+
+### `WOODPECKER_GITEA_CLIENT`
+> Default: empty
+
+Configures the Gitea OAuth client id. This is used to authorize access.
+
+### `WOODPECKER_GITEA_SECRET`
+> Default: empty
+
+Configures the Gitea OAuth client secret. This is used to authorize access.
+
+### `WOODPECKER_GITEA_SKIP_VERIFY`
+> Default: `false`
+
+Configure if SSL verification should be skipped.
+
+---
+
+### `WOODPECKER_BITBUCKET`
+> Default: `false`
+
+Enables the Bitbucket driver.
+
+### `WOODPECKER_BITBUCKET_CLIENT`
+> Default: empty
+
+Configures the Bitbucket OAuth client id. This is used to authorize access.
+
+### `WOODPECKER_BITBUCKET_SECRET`
+> Default: empty
+
+Configures the Bitbucket OAuth client secret. This is used to authorize access.
+
+---
+
+### `WOODPECKER_GITLAB`
+> Default: `false`
+
+Enables the GitLab driver.
+
+### `WOODPECKER_GITLAB_URL`
+> Default: `https://gitlab.com`
+
+Configures the GitLab server address.
+
+### `WOODPECKER_GITLAB_CLIENT`
+> Default: empty
+
+Configures the GitLab OAuth client id. This is used to authorize access.
+
+### `WOODPECKER_GITLAB_SECRET`
+> Default: empty
+
+Configures the GitLab OAuth client secret. This is used to authorize access.
+
+### `WOODPECKER_GITLAB_SKIP_VERIFY`
+> Default: `false`
+
+Configure if SSL verification should be skipped.
+
+---
+
+### `WOODPECKER_STASH`
+> Default: `false`
+
+Enables the Bitbucket Server driver.
+
+### `WOODPECKER_STASH_URL`
+> Default: empty
+
+Configures the Bitbucket Server address.
+
+### `WOODPECKER_STASH_CONSUMER_KEY`
+> Default: empty
+
+Configures your Bitbucket Server consumer key.
+
+### `WOODPECKER_STASH_CONSUMER_RSA`
+> Default: empty
+
+Configures the path to your Bitbucket Server private key file.
+
+### `WOODPECKER_STASH_CONSUMER_RSA_STRING`
+> Default: empty
+
+Configures your Bitbucket Server private key.
+
+### `WOODPECKER_STASH_GIT_USERNAME`
+> Default: empty
+
+This username is used to authenticate and clone all private repositories.
+
+### `WOODPECKER_STASH_GIT_PASSWORD`
+> Default: empty
+
+The password is used to authenticate and clone all private repositories.
+
+### `WOODPECKER_STASH_SKIP_VERIFY`
+> Default: `false`
+
+Configure if SSL verification should be skipped.
+
+---
+
+### `WOODPECKER_CODING`
+> Default: `false`
+
+Enables the Coding driver.
+
+### `WOODPECKER_CODING_URL`
+> Default: `https://coding.net`
+
+Configures the Coding server address.
+
+### `WOODPECKER_CODING_CLIENT`
+> Default: empty
+
+Configures the Coding OAuth client id. This is used to authorize access.
+
+### `WOODPECKER_CODING_SECRET`
+> Default: empty
+
+Configures the Coding OAuth client secret. This is used to authorize access.
+
+### `WOODPECKER_CODING_SCOPE`
+> Default: `user, project, project:depot`
+
+Comma-separated list of OAuth scopes.
+
+### `WOODPECKER_CODING_GIT_MACHINE`
+> Default: `git.coding.net`
+
+TODO
+
+### `WOODPECKER_CODING_GIT_USERNAME`
+> Default: empty
+
+This username is used to authenticate and clone all private repositories.
+
+### `WOODPECKER_CODING_GIT_PASSWORD`
+> Default: empty
+
+The password is used to authenticate and clone all private repositories.
+
+### `WOODPECKER_CODING_SKIP_VERIFY`
+> Default: `false`
+
+Configure if SSL verification should be skipped.