From 5f79739bc0b927d2c9c9154dafc4e9a690b47c71 Mon Sep 17 00:00:00 2001 From: KN4CK3R Date: Sun, 6 Feb 2022 21:21:57 +0100 Subject: [PATCH] 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 --- cmd/server/flags.go | 32 +- .../30-administration/10-server-config.md | 424 ++++++++++++++++++ 2 files changed, 440 insertions(+), 16 deletions(-) diff --git a/cmd/server/flags.go b/cmd/server/flags.go index ccc26b9dc..d2ec152b8 100644 --- 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 // diff --git a/docs/docs/30-administration/10-server-config.md b/docs/docs/30-administration/10-server-config.md index 9bbc1c4ea..4304f63b2 100644 --- 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.