This document intends to provide information on how to get the Vela application running locally.
For more information, please see our administration docs.
This section covers the dependencies required to get the Vela application running locally.
- Docker - building block for local development
- Docker Compose - start up local development
- GitHub OAuth Client - building block for local development
- Golang - for source code and dependency management
- Make - start up local development
NOTE: Please review the prerequisites section before moving forward.
This section covers the configuration required to get the Vela application running locally.
- Clone this repository to your workstation:
# clone the project
git clone [email protected]:go-vela/server.git $HOME/go-vela/server
- Navigate to the repository code:
# change into the cloned project directory
cd $HOME/go-vela/server
- If using GitHub Enterprise (default:
https://github.com
), add the Web URL to a local.env
file:
# add Github Enterprise Web URL to local `.env` file for `docker-compose`
echo "VELA_SCM_ADDR=<GitHub Enterprise Web URL>" >> .env
-
Create an OAuth App and obtain secrets for local development:
Application name
=Vela - local
(name of the OAuth application shouldn't matter)Homepage URL
=http://localhost:8888
(base URL of the web UI)Authorization callback URL
=http://localhost:8080/authenticate
(authenticate endpoint of the base URL of the server)
-
Add OAuth client secrets to a local
.env
file:
# add Github Client ID to local `.env` file for `docker-compose`
echo "VELA_SCM_CLIENT=<Github OAuth Client ID>" >> .env
# add Github Client Secret to local `.env` file for `docker-compose`
echo "VELA_SCM_SECRET=<Github OAuth Client Secret>" >> .env
NOTE: Please review the setup section before moving forward.
This section covers the commands required to get the Vela application running locally.
- Navigate to the repository code:
# change into the cloned project directory
cd $HOME/go-vela/server
- Run the repository code:
# execute the `up` target with `make`
make up
- Navigate to the web UI:
# opens a browser window to the page http://localhost:8888
open http://localhost:8888
NOTE: Please review the start section before moving forward.
In order to run a build in Vela, you'll need to add a repo to the locally running system.
click to reveal content
-
Navigate to the
Source Repositories
page @ http://localhost:8888/account/source-repos- For convenience, you can reference our documentation to learn how to enable a repo.
-
Click the blue drop-down arrow on the left side next to the org that contains the repo you want to enable.
-
Find the repo you want to enable in the drop-down list and click the blue
Enable
button on the right side.- You should receive a
success
message telling you<org>/<repo> enabled.
- You should receive a
-
Click the blue
View
button to navigate directly to the repo.- You should be redirected to http://localhost:8888//
NOTE: Please review the repo section before moving forward.
In order to run a build in Vela, you'll need to add a pipeline to the repo that has been added to the locally running system.
click to reveal content
-
Create a Vela pipeline to define a workflow for Vela to run.
- For convenience, you can reference our documentation to use one of our example pipelines.
-
Add the pipeline to the repo that was enabled above.
NOTE: Please review the pipeline section before moving forward.
In order to run a build in Vela, you'll need to capture a valid webhook payload to mock sending it to the locally running system.
click to reveal content
-
Review GitHub's documentation on webhooks
-
Find the recent delivery for the pipeline that was added to your repo.
-
Create a request locally for http://localhost:8080/webhook and replicate all parts from the recent delivery.
- You should use whatever tool feels most comfortable and natural to you (
curl
,Postman
,Insomnia
etc.). - You should replicate all the request headers and the request body from the recent delivery.
- You should use whatever tool feels most comfortable and natural to you (
-
Send the request and navigate directly to the repo (http://localhost:8888//) to watch the build run live.
This section covers the different services in the stack when the Vela application is running locally.
click to reveal content
The server
Docker compose service hosts the Vela server and API.
Known as the brains of the Vela application, this service is responsible for managing the state of application resources.
This includes managing resources in the system (repositories, users etc.) and storing resource data in the database.
Additionally, the server responds to event-driven requests (webhooks) which creates new builds to run on a worker.
For more information, please review the official documentation.
The worker
Docker compose service hosts the Vela build daemon.
Known as the brawn of the Vela application, this service is responsible for managing the state of build resources.
This includes pulling the build, provided by the server, from the queue to be run.
For more information, please review the official documentation.
The ui
Docker compose service hosts the Vela UI.
Known as the user interface for the Vela application, often referred to as the Vela UI, this service provides a means for utilizing and interacting with the Vela platform.
The Vela UI aims to provide users with an easy-to-use toolbox that supplies most of the functionality necessary for managing, investigating, and successfully troubleshooting Vela pipelines.
For more information, please review the official documentation.
The redis
Docker compose service hosts the Redis database.
This component is used for publishing builds to a FIFO queue.
For more information, please review the official documentation.
The postgres
Docker compose service hosts the Postgresql database.
This component is used for storing data at rest.
For more information, please review the official documentation.
The vault
Docker compose service hosts the HashiCorp Vault instance.
This component is used for storing sensitive data like secrets.
For more information, please review the official documentation.