diff --git a/lit/docs/install.lit b/lit/docs/install.lit index 8a614ce5..9d0c5a9d 100644 --- a/lit/docs/install.lit +++ b/lit/docs/install.lit @@ -45,3 +45,4 @@ The high-level steps to follow for installing Concourse are: \include-section{install/web.lit} \include-section{install/worker.lit} \include-section{install/upgrading.lit} +\include-section{install/install-guides.lit} diff --git a/lit/docs/install/docker-compose.lit b/lit/docs/install/docker-compose.lit new file mode 100644 index 00000000..fec10517 --- /dev/null +++ b/lit/docs/install/docker-compose.lit @@ -0,0 +1,163 @@ +\title{\aux{Install Concourse with} Docker Compose}{install-docker-compose} + +\use-plugin{concourse-docs} + +This guide will show you how to install Concourse on any Linux system +using \link{Docker Compose}{https://docs.docker.com/compose/}. + +This guide makes the following assumptions: +\ordered-list{ + The host system has Docker installed already. +}{ + You have a PostgreSQL database running somewhere already. You created a + database called \code{concourse} and created a user for Concourse to + authenticate as. +}{ + You have generated the necessary + \reference{generating-keys}{encryption Keys}. +}{ + The host system the Web node will be running on is exposed to the + internet and can therefore accept inbound traffic on port \code{443}. +}{ + The Web and Worker node are being installed on separate servers and you + will figure out networking between the two servers. The Web node needs + to accept ingress traffic on the TSA port (default is port \code{2222}) + from the Worker node(s). +} + + +\section{ + \title{Setup Web Node}{docker-web} + + You can do the following from any directory on your system. This guide + will assume all work is done in \code{~/concourse}. + + Create a directory called \code{keys} (\code{~/concourse/keys}). Place + the following encryption keys inside the new directory: + \list{ + \code{session_signing_key} + }{ + \code{tsa_host_key} + }{ + \code{worker_key.pub} + } + + Next, create a \code{docker-compose.yml} file + (\code{~/concourse/docker-compose.yml}) with the following content: + + \codeblock{yaml}{{{ + services: + web: + image: docker.io/concourse/concourse:latest + command: web + restart: "unless-stopped" + ports: + - "443:8080" + - "2222:2222" + volumes: + - ~/concourse/keys:/concourse-keys:ro + environment: + CONCOURSE_EXTERNAL_URL: https://ci.example.com + CONCOURSE_ENABLE_LETS_ENCRYPT: "true" + CONCOURSE_SESSION_SIGNING_KEY: /concourse-keys/session_signing_key + CONCOURSE_TSA_AUTHORIZED_KEYS: /concourse-keys/worker_key.pub + CONCOURSE_TSA_HOST_KEY: /concourse-keys/tsa_host_key + CONCOURSE_POSTGRES_HOST: + CONCOURSE_POSTGRES_USER: + CONCOURSE_POSTGRES_PASSWORD: + CONCOURSE_POSTGRES_DATABASE: concourse + CONCOURSE_ADD_LOCAL_USER: test:test + CONCOURSE_MAIN_TEAM_LOCAL_USER: test + CONCOURSE_CLUSTER_NAME: Concourse + CONCOURSE_ENABLE_ACROSS_STEP: "true" + CONCOURSE_ENABLE_REDACT_SECRETS: "true" + CONCOURSE_ENABLE_PIPELINE_INSTANCES: "true" + CONCOURSE_ENABLE_CACHE_STREAMED_VOLUMES: "true" + logging: + driver: local + options: + max-size: "100m" + }}} + + \aside{ + The above file configues the web node with + \reference{local-auth}{local user authentication} with the username + and password set to \code{test}. You will probably want to configure + your web node with one of the other + \reference{configuring-auth}{authentication providers} and remove the + \code{*_LOCAL_USER} environment variables. + } + + You can start the Web node by running: + + \codeblock{bash}{{{ + docker compose up -d + }}} + + You should then be able to access Concourse from the + \code{CONCOURSE_EXTERNAL_URL} you specified. + + If you're using local authentication you can login using the + \reference{fly}. + + \codeblock{bash}{{{ + fly -t ci -c https://ci.example.com -u test -p test + }}} +} + +\section{ + \title{Setup Worker Node}{docker-worker} + + You can do the following from any directory on your system. This guide + will assume all work is done in \code{~/concourse}. + + Create a directory called \code{keys} (\code{~/concourse/keys}). Place + the following encryption keys inside the new directory: + \list{ + \code{tsa_host_key.pub} + }{ + \code{worker_key} + } + + Next, create a \code{docker-compose.yml} file + (\code{~/concourse/docker-compose.yml}) with the following content: + + \codeblock{yaml}{{{ + services: + worker: + image: docker.io/concourse/concourse:latest + command: worker + privileged: true + restart: "unless-stopped" + stop_signal: SIGUSR2 + volumes: + - ~/concourse/keys:/concourse-keys:ro + environment: + CONCOURSE_NAME: worker-01 + CONCOURSE_RUNTIME: containerd + CONCOURSE_BAGGAGECLAIM_DRIVER: overlay + CONCOURSE_TSA_PUBLIC_KEY: /concourse-keys/tsa_host_key.pub + CONCOURSE_TSA_WORKER_PRIVATE_KEY: /concourse-keys/worker_key + CONCOURSE_TSA_HOST: :2222 + logging: + driver: local + options: + max-size: "100m" + }}} + + \aside{ + If your pipelines are having issues with DNS resolution please read + \reference{worker-troubleshoot-dns}{this section}. + } + + You can start the Worker node by running: + + \codeblock{bash}{{{ + docker compose up -d + }}} + + Using the \reference{fly} you should be able to see the worker successfully + connected to the Web node by running \code{fly workers}. + + Congratulations, you've successfully deployed a Concourse cluster! +} diff --git a/lit/docs/install/helm.lit b/lit/docs/install/helm.lit new file mode 100644 index 00000000..c5a546f7 --- /dev/null +++ b/lit/docs/install/helm.lit @@ -0,0 +1,3 @@ +\title{\aux{Install Concourse with} Helm}{install-helm} + +\use-plugin{concourse-docs} diff --git a/lit/docs/install/install-guides.lit b/lit/docs/install/install-guides.lit new file mode 100644 index 00000000..96f5ec3b --- /dev/null +++ b/lit/docs/install/install-guides.lit @@ -0,0 +1,11 @@ +\title{Install Guides}{install-guides} + +\use-plugin{concourse-docs} + +\table-of-contents + +\split-sections + +\include-section{systemd.lit} +\include-section{docker-compose.lit} +\include-section{helm.lit} diff --git a/lit/docs/install/systemd.lit b/lit/docs/install/systemd.lit new file mode 100644 index 00000000..c4f78d02 --- /dev/null +++ b/lit/docs/install/systemd.lit @@ -0,0 +1,271 @@ +\title{\aux{Install Concourse With} Systemd}{install-systemd} + +\use-plugin{concourse-docs} + +This guide will show you how to install Concourse on any Linux system +running \link{Systemd}{https://github.com/systemd/systemd}. + +This guide makes the following assumptions: +\ordered-list{ + You have a PostgreSQL database running somewhere already. You created a + database called \code{concourse} and created a user for Concourse to + authenticate as. +}{ + You have generated the necessary + \reference{generating-keys}{encryption Keys}. +}{ + The Web node will be directly exposed to the internet and can therefore + accept inbound traffic on port \code{443}. +}{ + The Web and Worker node are being installed on separate servers and you + will figure out networking between the two servers. The Web node needs + to accept ingress traffic on the TSA port (default is port \code{2222}) + from the Worker node(s). +} + +\section{ + \title{Install the Concourse CLI}{systemd-concourse-cli} + The first step is to install the \reference{concourse-cli}. We will + install the CLI in \code{/use/local/concourse}, but you can choose a + different install location. + + Run the following commands to install the Concourse CLI. \bold{You need to do + this on both your Web and Worker servers.} + \codeblock{bash}{{{ + CONCOURSE_VERSION="" + CONCOURSE_TAR="concourse.tgz" + CONCOURSE_URL="https://github.com/concourse/concourse/releases/download/v${CONCOURSE_VERSION}/concourse-${CONCOURSE_VERSION}-linux-amd64.tgz" + curl -L --output ./${CONCOURSE_TAR} ${CONCOURSE_URL} + tar xzf ./${CONCOURSE_TAR} -C /usr/local/ + rm ./${CONCOURSE_TAR} + }}} + + If you want to make running the Concourse CLI easier, add + \code{/usr/local/concourse/bin} to your \code{PATH}. + + \codeblock{bash}{{{ + PATH="$PATH:/usr/local/concourse/bin" + }}} + + You can move on to setting up the Web and Worker servers. +} + +\section{ + \title{Setup Web Node}{systemd-web} + First lets create a new user and group for the Web node to run as: + + \codeblock{bash}{{{ + addgroup --system "concourse" + adduser \ + --system \ + --ingroup "concourse" \ + --no-create-home \ + --disabled-password \ + --disabled-login \ + --comment "concourse web user" \ + "concourse" + }}} + + Next, place the following keys (previously generated) in + \code{/usr/local/concourse/keys/}: + \list{ + \code{session_signing_key} + }{ + \code{tsa_host_key} + }{ + \code{worker_key.pub} + } + + Next create a file named \code{web.env} in \code{/usr/local/concourse/} that + will be used to configure the Web node. This is where you can \reference{configuring-auth}{configure + authentication} to Concourse and all other settings found when you run + \code{concourse web --help}. + + Change the following values: + \list{ + \code{CONCOURSE_POSTGRES_*} - Used to tell Concourse how to connect to PostgreSQL + }{ + \code{CONCOURSE_EXTERNAL_URL} - The URL users will use to access the web + UI. A Let's Encrypt certificate will also be generated for the hostname in + this URL. + } + + \codeblock{}{{{ + PATH=/usr/local/concourse/bin + CONCOURSE_EXTERNAL_URL=https://ci.example.com + CONCOURSE_ENABLE_LETS_ENCRYPT=true + CONCOURSE_TLS_BIND_PORT=443 + CONCOURSE_POSTGRES_HOST=db.example.com + CONCOURSE_POSTGRES_USER= + CONCOURSE_POSTGRES_PASSWORD= + CONCOURSE_POSTGRES_DATABASE=concourse + CONCOURSE_SESSION_SIGNING_KEY=/usr/local/concourse/keys/session_signing_key + CONCOURSE_TSA_HOST_KEY=/usr/local/concourse/keys/tsa_host_key + CONCOURSE_TSA_AUTHORIZED_KEYS=/usr/local/concourse/keys/worker_key.pub + CONCOURSE_CLUSTER_NAME=Concourse + CONCOURSE_MAIN_TEAM_LOCAL_USER=local + CONCOURSE_ADD_LOCAL_USER=test:test + CONCOURSE_ENABLE_ACROSS_STEP=true + CONCOURSE_ENABLE_REDACT_SECRETS=true + CONCOURSE_ENABLE_PIPELINE_INSTANCES=true + CONCOURSE_ENABLE_CACHE_STREAMED_VOLUMES=true + }}} + + \aside{ + The above file configues the web node with + \reference{local-auth}{local user authentication} with the username + and password set to \code{test}. You will probably want to configure + your web node with one of the other + \reference{configuring-auth}{authentication providers} and remove the + \code{*_LOCAL_USER} environment variables. + } + + Set the file permissions to read-only: + \codeblock{bash}{{{ + chmod 0444 web.env + }}} + + Ensure the entire \code{/usr/local/concourse} folder is owned by the + \code{concourse} user and group: + + \codeblock{bash}{{{ + chown -R concourse:concourse /usr/local/concourse + }}} + + We can now created a new Systemd Unit file at + \code{/etc/systemd/system/} named \code{concourse-web.service}. Place + the following configuration in the unit file: + + \codeblock{}{{{ + [Unit] + Description=Concourse Web node + [Service] + User=concourse + Group=concourse + EnvironmentFile=/usr/local/concourse/web.env + ExecStart=/usr/local/concourse/bin/concourse web + Restart=on-failure + RestartSec=3 + KillSignal=SIGTERM + TimeoutStopSec=60 + [Install] + WantedBy=default.target + }}} + + Finally enable and start the Web service: + \codeblock{bash}{{{ + systemctl daemon-reload + systemctl enable concourse-web + systemctl start concourse-web + }}} + + Check the status of the service: + \codeblock{bash}{{{ + systemctl status concourse-web + }}} + + If the service isn't staying up, check the logs: + \codeblock{bash}{{{ + journalctl -u concourse-web + }}} + + You should then be able to access Concourse from the + \code{CONCOURSE_EXTERNAL_URL} you specified. + + If you're using local authentication you can login using the + \reference{fly}. + + \codeblock{bash}{{{ + fly -t ci -c https://ci.example.com -u test -p test + }}} +} + +\section{ + \title{Setup Worker Node}{systemd-worker} + The Worker has to run as root so there is no user to create. We can go + straight to configuring the Worker. + + Ensure the following keys (previously generated) are located in + \code{/usr/local/concourse/keys/}: + \list{ + \code{tsa_host_key.pub} + }{ + \code{worker_key} + } + + Create the directory \code{/opt/concourse} where the worker will place + runtime artifacts. Files in this directory are temporary and are managed by + the worker. + + Next create a file named \code{worker.env} in \code{/usr/local/concourse/} + that will be used to configure the Worker. To see all possible configuration + options run \code{concourse worker --help} and read more about + \reference{worker-node}{running a worker node}. + + \codeblock{}{{{ + PATH=/usr/local/concourse/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin + CONCOURSE_NAME=worker-01 + CONCOURSE_WORK_DIR=/opt/concourse/worker + CONCOURSE_TSA_HOST=":2222" + CONCOURSE_TSA_PUBLIC_KEY=/usr/local/concourse/keys/tsa_host_key.pub + CONCOURSE_TSA_WORKER_PRIVATE_KEY=/usr/local/concourse/keys/worker_key + CONCOURSE_RUNTIME=containerd + CONCOURSE_BAGGAGECLAIM_DRIVER=overlay + }}} + + \aside{ + If your pipelines are having issues with DNS resolution please read + \reference{worker-troubleshoot-dns}{this section}. + } + + The \code{CONCOURSE_NAME} must be unique per worker. Having two workers with + the same name will result in a lot of weirdness. + + Set the file permissions to read-only: + \codeblock{bash}{{{ + chmod 0444 worker.env + }}} + + We can now created a new Systemd Unit file at + \code{/etc/systemd/system/} named \code{concourse-worker.service}. Place + the following configuration in the unit file: + + \codeblock{}{{{ + [Unit] + Description=Concourse Worker + [Service] + User=root + Group=root + EnvironmentFile=/usr/local/concourse/worker.env + ExecStart=/usr/local/concourse/bin/concourse worker + Restart=on-failure + RestartSec=3 + KillSignal=SIGUSR2 + SendSIGKILL=yes + TimeoutStopSec=300 + [Install] + WantedBy=default.target + }}} + + Finally enable and start the Worker service: + \codeblock{bash}{{{ + systemctl daemon-reload + systemctl enable concourse-worker + systemctl start concourse-worker + }}} + + Check the status of the service: + \codeblock{bash}{{{ + systemctl status concourse-worker + }}} + + If the service isn't staying up, check the logs: + \codeblock{bash}{{{ + journalctl -u concourse-worker + }}} + + Using the \reference{fly} you should be able to see the worker successfully + connected to the Web node by running \code{fly workers}. + + Congratulations, you've successfully deployed a Concourse cluster! +} diff --git a/lit/docs/install/worker.lit b/lit/docs/install/worker.lit index b4ae0551..42e8bd09 100644 --- a/lit/docs/install/worker.lit +++ b/lit/docs/install/worker.lit @@ -9,7 +9,7 @@ decide much on its own. \table-of-contents \section{ - \title{Prerequisites}{worker-prerequisites} + \title{prerequisites}{worker-prerequisites} \list{ Linux: We test and support the following distributions. Minimum kernel @@ -653,7 +653,7 @@ decide much on its own. } \section{ - \title{Troubleshooting and fixing DNS resolution} + \title{Troubleshooting and fixing DNS resolution}{worker-troubleshoot-dns} \aside{ \bold{Note}: The Guardian runtime took care of a lot of container