diff --git a/docs/docs/10-intro.md b/docs/docs/10-intro.md index cb8dc415b..cc28b1f86 100644 --- a/docs/docs/10-intro.md +++ b/docs/docs/10-intro.md @@ -91,4 +91,4 @@ See [plugin docs](./20-usage/51-plugins/10-plugins.md). ## Continue reading - [Create a Woodpecker pipeline for your repository](./20-usage/10-intro.md) -- [Setup your own Woodpecker instance](./30-administration/00-setup.md) +- [Setup your own Woodpecker instance](./30-administration/00-deployment/00-overview.md) diff --git a/docs/docs/30-administration/00-deployment/00-overview.md b/docs/docs/30-administration/00-deployment/00-overview.md new file mode 100644 index 000000000..214c615c0 --- /dev/null +++ b/docs/docs/30-administration/00-deployment/00-overview.md @@ -0,0 +1,73 @@ +# Overview + +A Woodpecker deployment consists of two parts: + +- A server which is the heart of Woodpecker and ships the web interface. +- Next to one server you can deploy any number of agents which will run the pipelines. + +> Each agent is able to process one pipeline step by default. +> +> If you have 4 agents installed and connected to the Woodpecker server, your system will process 4 workflows in parallel. +> +> You can add more agents to increase the number of parallel workflows or set the agent's `WOODPECKER_MAX_WORKFLOWS=1` environment variable to increase the number of parallel workflows for that agent. + +## Which version of Woodpecker should I use? + +Woodpecker is having two different kinds of releases: **stable** and **next**. + +To find out more about the differences between the two releases, please read the [FAQ](/faq#which-version-of-woodpecker-should-i-use). + +## Hardware Requirements + +Below are minimal resources requirements for Woodpecker components itself: + +| Component | Memory | CPU | +| --------- | ------ | --- | +| Server | 200 MB | 1 | +| Agent | 32 MB | 1 | + +Note, that those values do not include the operating system or workload (pipelines execution) resources consumption. + +In addition you need at least some kind of database which requires additional resources depending on the selected database system. + +## Installation + +You can install Woodpecker on multiple ways: + +- Using [docker-compose](./10-docker-compose.md) with the official [container images](./10-docker-compose.md#docker-images) +- Using [Kubernetes](./20-kubernetes.md) via the Woodpecker Helm chart +- Using binaries, DEBs or RPMs you can download from [latest release](https://github.com/woodpecker-ci/woodpecker/releases/latest) + +## Authentication + +Authentication is done using OAuth and is delegated to your forge which is configured using environment variables. + +See the complete reference for all supported forges [here](../11-forges/10-overview.md). + +## Database + +By default Woodpecker uses a SQLite database which requires zero installation or configuration. See the [database settings](../30-database.md) page to further configure it or use MySQL or Postgres. + +## SSL + +Woodpecker supports SSL configuration by using Let's encrypt or by using own certificates. See the [SSL guide](../60-ssl.md). You can also put it behind a [reverse proxy](#behind-a-proxy) + +## Metrics + +A [Prometheus endpoint](../90-prometheus.md) is exposed. + +## Behind a proxy + +See the [proxy guide](../70-proxy.md) if you want to see a setup behind Apache, Nginx, Caddy or ngrok. + +In the case you need to use Woodpecker with a URL path prefix (like: https://example.org/woodpecker/), you can use the option [`WOODPECKER_ROOT_PATH`](../10-server-config.md#woodpecker_root_path). + +## Third-party installation methods + +:::info +These installation methods are not officially supported. If you experience issues with them, please open issues in the specific repositories. +::: + +- Using [NixOS](./30-nixos.md) via the [NixOS module](https://search.nixos.org/options?channel=unstable&size=200&sort=relevance&query=woodpecker) +- [Using YunoHost](https://apps.yunohost.org/app/woodpecker) +- [On Cloudron](https://www.cloudron.io/store/org.woodpecker_ci.cloudronapp.html) diff --git a/docs/docs/30-administration/00-deployment/10-docker-compose.md b/docs/docs/30-administration/00-deployment/10-docker-compose.md new file mode 100644 index 000000000..99b19c392 --- /dev/null +++ b/docs/docs/30-administration/00-deployment/10-docker-compose.md @@ -0,0 +1,154 @@ +# docker-compose + +The below [docker-compose](https://docs.docker.com/compose/) configuration can be used to start a Woodpecker server with a single agent. + +It relies on a number of environment variables that you must set before running `docker-compose up`. The variables are described below. + +```yaml +# docker-compose.yml +version: '3' + +services: + woodpecker-server: + image: woodpeckerci/woodpecker-server:latest + ports: + - 8000:8000 + volumes: + - woodpecker-server-data:/var/lib/woodpecker/ + environment: + - WOODPECKER_OPEN=true + - WOODPECKER_HOST=${WOODPECKER_HOST} + - WOODPECKER_GITHUB=true + - WOODPECKER_GITHUB_CLIENT=${WOODPECKER_GITHUB_CLIENT} + - WOODPECKER_GITHUB_SECRET=${WOODPECKER_GITHUB_SECRET} + - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET} + + woodpecker-agent: + image: woodpeckerci/woodpecker-agent:latest + command: agent + restart: always + depends_on: + - woodpecker-server + volumes: + - woodpecker-agent-config:/etc/woodpecker + - /var/run/docker.sock:/var/run/docker.sock + environment: + - WOODPECKER_SERVER=woodpecker-server:9000 + - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET} + +volumes: + woodpecker-server-data: + woodpecker-agent-config: +``` + +Woodpecker needs to know its own address. You must therefore provide the public address of it in `://` format. Please omit trailing slashes: + +```diff +# docker-compose.yml +version: '3' + +services: + woodpecker-server: + [...] + environment: + - [...] ++ - WOODPECKER_HOST=${WOODPECKER_HOST} +``` + +Woodpecker can also have its port's configured. It uses a separate port for gRPC and for HTTP. The agent performs gRPC calls and connects to the gRPC port. +They can be configured with ADDR variables: + +```diff +# docker-compose.yml +version: '3' +services: + woodpecker-server: + [...] + environment: + - [...] ++ - WOODPECKER_GRPC_ADDR=${WOODPECKER_GRPC_ADDR} ++ - WOODPECKER_SERVER_ADDR=${WOODPECKER_HTTP_ADDR} +``` + +Reverse proxying can also be [configured for gRPC](../proxy#caddy). If the agents are connecting over the internet, it should also be SSL encrypted. The agent then needs to be configured to be secure: + +```diff +# docker-compose.yml +version: '3' +services: + woodpecker-server: + [...] + environment: + - [...] ++ - WOODPECKER_GRPC_SECURE=true # defaults to false ++ - WOODPECKER_GRPC_VERIFY=true # default +``` + +As agents run pipeline steps as docker containers they require access to the host machine's Docker daemon: + +```diff +# docker-compose.yml +version: '3' + +services: + [...] + woodpecker-agent: + [...] ++ volumes: ++ - /var/run/docker.sock:/var/run/docker.sock +``` + +Agents require the server address for agent-to-server communication. The agent connects to the server's gRPC port: + +```diff +# docker-compose.yml +version: '3' + +services: + woodpecker-agent: + [...] + environment: ++ - WOODPECKER_SERVER=woodpecker-server:9000 +``` + +The server and agents use a shared secret to authenticate communication. This should be a random string of your choosing and should be kept private. You can generate such string with `openssl rand -hex 32`: + +```diff +# docker-compose.yml +version: '3' + +services: + woodpecker-server: + [...] + environment: + - [...] ++ - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET} + woodpecker-agent: + [...] + environment: + - [...] ++ - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET} +``` + +## Docker images + +Image variants: + +- The `latest` image is the latest stable release +- The `vX.X.X` images are stable releases +- The `vX.X` images are based on the current release branch (e.g. `release/v1.0`) and can be used to get bugfixes asap +- The `next` images are based on the current `main` branch and should not be used for production environments + +``` bash +# server +docker pull woodpeckerci/woodpecker-server:latest +docker pull woodpeckerci/woodpecker-server:latest-alpine + +# agent +docker pull woodpeckerci/woodpecker-agent:latest +docker pull woodpeckerci/woodpecker-agent:latest-alpine + +# cli +docker pull woodpeckerci/woodpecker-cli:latest +docker pull woodpeckerci/woodpecker-cli:latest-alpine +``` diff --git a/docs/docs/30-administration/00-deployment/20-kubernetes.md b/docs/docs/30-administration/00-deployment/20-kubernetes.md new file mode 100644 index 000000000..049b460c6 --- /dev/null +++ b/docs/docs/30-administration/00-deployment/20-kubernetes.md @@ -0,0 +1,10 @@ +# Kubernetes + +We recommended to deploy Woodpecker using the [Woodpecker helm chart](https://github.com/woodpecker-ci/helm). +Have a look at the [`values.yaml`](https://github.com/woodpecker-ci/helm/blob/main/values.yaml) config files for all available settings. + +The chart contains two subcharts, `server` and `agent` which are automatically configured as needed. +The chart started off with two independent charts but was merged into one to simplify the deployment at start of 2023. + +A couple of backend-specific config env vars exists which are described in the [kubernetes backend docs](../22-backends/40-kubernetes.md). + diff --git a/docs/docs/30-administration/22-backends/50-nixos.md b/docs/docs/30-administration/00-deployment/30-nixos.md similarity index 99% rename from docs/docs/30-administration/22-backends/50-nixos.md rename to docs/docs/30-administration/00-deployment/30-nixos.md index 1ee27bacc..148fbd581 100644 --- a/docs/docs/30-administration/22-backends/50-nixos.md +++ b/docs/docs/30-administration/00-deployment/30-nixos.md @@ -1,4 +1,4 @@ -# NixOS Deployment +# NixOS :::info Note that this module is not maintained by the woodpecker-developers. diff --git a/docs/docs/30-administration/00-deployment/_category_.yml b/docs/docs/30-administration/00-deployment/_category_.yml new file mode 100644 index 000000000..af150d571 --- /dev/null +++ b/docs/docs/30-administration/00-deployment/_category_.yml @@ -0,0 +1,3 @@ +label: 'Deployment' +collapsible: true +collapsed: true diff --git a/docs/docs/30-administration/00-setup.md b/docs/docs/30-administration/00-setup.md deleted file mode 100644 index b7d4fb3fc..000000000 --- a/docs/docs/30-administration/00-setup.md +++ /dev/null @@ -1,206 +0,0 @@ -# Setup - -A Woodpecker deployment consists of two parts: - -- A server which is the heart of Woodpecker and ships the web interface. -- Next to one server you can deploy any number of agents which will run the pipelines. - -> Each agent is able to process one pipeline step by default. -> -> If you have 4 agents installed and connected to the Woodpecker server, your system will process 4 builds in parallel. -> -> You can add more agents to increase the number of parallel steps or set the agent's `WOODPECKER_MAX_WORKFLOWS=1` environment variable to increase the number of parallel workflows for that agent. - -## Which version of Woodpecker should I use? - -Woodpecker is having two different kinds of releases: **stable** and **next**. - -To find out more about the differences between the two releases, please read the [FAQ](/faq). - -## Hardware Requirements - -Below are resources requirements for Woodpecker components itself: - -| Component | Memory | CPU | -| --------- | ------ | --- | -| Server | 200 MB | 1 | -| Agent | 32 MB | 1 | - -Note, that those values do not include the operating system or workload (pipelines execution) resources consumption. - -In addition you need at least some kind of database which requires additional resources depending on the selected database system. - -## Installation - -You can install Woodpecker on multiple ways: - -- Using [docker-compose](#docker-compose) with the official [container images](../80-downloads.md#docker-images) -- Using [Kubernetes](#kubernetes) via the Woodpeckers Helm chart -- Using [NixOS](#nixos) via the [NixOS module](https://search.nixos.org/options?channel=unstable&size=200&sort=relevance&query=woodpecker) -- Using [binaries](../80-downloads.md) - -### docker-compose - -The below [docker-compose](https://docs.docker.com/compose/) configuration can be used to start a Woodpecker server with a single agent. - -It relies on a number of environment variables that you must set before running `docker-compose up`. The variables are described below. - -```yaml -# docker-compose.yml -version: '3' - -services: - woodpecker-server: - image: woodpeckerci/woodpecker-server:latest - ports: - - 8000:8000 - volumes: - - woodpecker-server-data:/var/lib/woodpecker/ - environment: - - WOODPECKER_OPEN=true - - WOODPECKER_HOST=${WOODPECKER_HOST} - - WOODPECKER_GITHUB=true - - WOODPECKER_GITHUB_CLIENT=${WOODPECKER_GITHUB_CLIENT} - - WOODPECKER_GITHUB_SECRET=${WOODPECKER_GITHUB_SECRET} - - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET} - - woodpecker-agent: - image: woodpeckerci/woodpecker-agent:latest - command: agent - restart: always - depends_on: - - woodpecker-server - volumes: - - woodpecker-agent-config:/etc/woodpecker - - /var/run/docker.sock:/var/run/docker.sock - environment: - - WOODPECKER_SERVER=woodpecker-server:9000 - - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET} - -volumes: - woodpecker-server-data: - woodpecker-agent-config: -``` - -Woodpecker needs to know its own address. You must therefore provide the public address of it in `://` format. Please omit trailing slashes: - -```diff -# docker-compose.yml -version: '3' - -services: - woodpecker-server: - [...] - environment: - - [...] -+ - WOODPECKER_HOST=${WOODPECKER_HOST} -``` - -Woodpecker can also have its port's configured. It uses a separate port for gRPC and for HTTP. The agent performs gRPC calls and connects to the gRPC port. -They can be configured with ADDR variables: - -```diff -# docker-compose.yml -version: '3' -services: - woodpecker-server: - [...] - environment: - - [...] -+ - WOODPECKER_GRPC_ADDR=${WOODPECKER_GRPC_ADDR} -+ - WOODPECKER_SERVER_ADDR=${WOODPECKER_HTTP_ADDR} -``` - -Reverse proxying can also be [configured for gRPC](./proxy#caddy). If the agents are connecting over the internet, it should also be SSL encrypted. The agent then needs to be configured to be secure: - -```diff -# docker-compose.yml -version: '3' -services: - woodpecker-server: - [...] - environment: - - [...] -+ - WOODPECKER_GRPC_SECURE=true # defaults to false -+ - WOODPECKER_GRPC_VERIFY=true # default -``` - -As agents run pipeline steps as docker containers they require access to the host machine's Docker daemon: - -```diff -# docker-compose.yml -version: '3' - -services: - [...] - woodpecker-agent: - [...] -+ volumes: -+ - /var/run/docker.sock:/var/run/docker.sock -``` - -Agents require the server address for agent-to-server communication. The agent connects to the server's gRPC port: - -```diff -# docker-compose.yml -version: '3' - -services: - woodpecker-agent: - [...] - environment: -+ - WOODPECKER_SERVER=woodpecker-server:9000 -``` - -The server and agents use a shared secret to authenticate communication. This should be a random string of your choosing and should be kept private. You can generate such string with `openssl rand -hex 32`: - -```diff -# docker-compose.yml -version: '3' - -services: - woodpecker-server: - [...] - environment: - - [...] -+ - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET} - woodpecker-agent: - [...] - environment: - - [...] -+ - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET} -``` - -### Kubernetes - -We recommended to deploy Woodpecker using the [Woodpecker helm chart](https://github.com/woodpecker-ci/helm). -Have a look at the [`values.yaml`](https://github.com/woodpecker-ci/helm/blob/main/values.yaml) config files for all available settings. - -The chart contains two subcharts, `server` and `agent` which are automatically configured as needed. -The chart started off with two independent charts but was merged into one to simplify the deployment at start of 2023. - -A couple of backend-specific config env vars exists which are described in the [kubernetes backend docs](./22-backends/40-kubernetes.md). - -## Authentication - -Authentication is done using OAuth and is delegated to your forge which is configured by using environment variables. The example above demonstrates basic GitHub integration. - -See the complete reference for all supported forges [here](./11-forges/10-overview.md). - -## Database - -By default Woodpecker uses a SQLite database which requires zero installation or configuration. See the [database settings](./30-database.md) page to further configure it or use MySQL or Postgres. - -## SSL - -Woodpecker supports SSL configuration by using Let's encrypt or by using own certificates. See the [SSL guide](./60-ssl.md). - -## Metrics - -A [Prometheus endpoint](./90-prometheus.md) is exposed. - -## Behind a proxy - -See the [proxy guide](./70-proxy.md) if you want to see a setup behind Apache, Nginx, Caddy or ngrok. - -In the case you need to use Woodpecker with a URL path prefix (like: https://example.org/woodpecker/), you can use the option [`WOODPECKER_ROOT_PATH`](./10-server-config.md#woodpecker_root_path). diff --git a/docs/docs/30-administration/20-migrate-from-drone.md b/docs/docs/30-administration/20-migrate-from-drone.md deleted file mode 100644 index 8bc51f796..000000000 --- a/docs/docs/30-administration/20-migrate-from-drone.md +++ /dev/null @@ -1,16 +0,0 @@ -# Migrate from Drone to Woodpecker - -## Migrate from Drone >= v1.0.0 - -We currently do not provide a way to do so. -If you are interested or have a custom script to do so, please get in contact with us. - -## Migrate from Drone <= v0.8 - -- Make sure you are already running Drone v0.8 -- Upgrade to Woodpecker v0.14.4, migration will be done during startup -- If you are using Sqlite3, rename `drone.sqlite` to `woodpecker.sqlite` and - rename or adjust the mount/folder of the volume from `/var/lib/drone/` - to `/var/lib/woodpecker/` -- Upgrade to Woodpecker v1.0.0, the migration will be performed during - startup diff --git a/docs/docs/80-downloads.md b/docs/docs/80-downloads.md deleted file mode 100644 index e18c00e42..000000000 --- a/docs/docs/80-downloads.md +++ /dev/null @@ -1,34 +0,0 @@ -# Downloads - -## Which version of Woodpecker should I use? - -Woodpecker is having two different kinds of releases: **stable** and **next**. - -To find out more about the differences between the two releases, please read the [FAQ](/faq). - -## Binaries & DEB, RPM - -[Latest release](https://github.com/woodpecker-ci/woodpecker/releases/latest) - -## Docker images - -Image variants: - -- The `latest` image is the latest stable release -- The `vX.X.X` images are stable releases -- The `vX.X` images are based on the current release branch (e.g. `release/v1.0`) and can be used to get bugfixes asap -- The `next` images are based on the current `main` branch and should not be used for production environments - -``` bash -# server -docker pull woodpeckerci/woodpecker-server:latest -docker pull woodpeckerci/woodpecker-server:latest-alpine - -# agent -docker pull woodpeckerci/woodpecker-agent:latest -docker pull woodpeckerci/woodpecker-agent:latest-alpine - -# cli -docker pull woodpeckerci/woodpecker-cli:latest -docker pull woodpeckerci/woodpecker-cli:latest-alpine -``` diff --git a/docs/docs/91-migrations.md b/docs/docs/91-migrations.md index f7334eec3..4d3beae49 100644 --- a/docs/docs/91-migrations.md +++ b/docs/docs/91-migrations.md @@ -120,3 +120,13 @@ Some versions need some changes to the server configuration or the pipeline conf ## 0.14.0 No breaking changes + +## From Drone + +:::warning +Migration from Drone is only possible if you were running Drone <= v0.8. +::: + +1. Make sure you are already running Drone v0.8 +2. Upgrade to Woodpecker v0.14.4, migration will be done during startup +3. Upgrade to the latest Woodpecker version. Pay attention to the breaking changes listed above. diff --git a/docs/src/pages/faq.md b/docs/src/pages/faq.md index 58128520e..0b981e4e1 100644 --- a/docs/src/pages/faq.md +++ b/docs/src/pages/faq.md @@ -18,12 +18,10 @@ Woodpecker is having two different kinds of releases: **stable** and **next**. The **stable** releases (currently version 1.0) are long-term supported (LTS) stable versions. The stable releases are only getting bugfixes. -The **next** release contains all bugfixes and features from `main` branch. Normally it should be pretty stable, but as its frequently updated, it might contain some bugs from time to time. +The **next** release contains all bugfixes and features from `main` branch. Normally it should be pretty stable, but as its frequently updated, it might contain some bugs from time to time. There are no binaries for this version. If you want all (new) features of Woodpecker and are willing to accept some possible bugs from time to time, you should use the next release otherwise use the stable release. -You can find download links for the different releases in the [download section](/docs/downloads). - ## How to debug clone issues (And what to do with an error message like `fatal: could not read Username for 'https://': No such device or address`)