Gitlab is a great development tool, getting better with every release. They give you access to their new-ish pipelining features on Gitlab.com for free. However, I wanted to setup the Gitlab Runner (this is what executes your CI build) on my own VPS using Docker. Gitlab makes this very easy to install, but the documentaion is spread out when it comes to setup and execution. I thought an all in one document showing all the steps would be helpful to the community.
I am hoping this post will help out others looking to run their Elixir/Phoenix application tests through the CI pipeline using their own VPS.
All commands were executed on my VPS as the root user. If you are logged in as a user that has sudo access, you will need to prepend all commands with
Prerequisites: A VPS or similar server (virtualbox, docker, …)
Setup the Gitlab Runner
Run on your VPS
Install Gitlab Runner Repo
curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-ci-multi-runner/script.deb.sh
Install Gitlab Runner
apt-get install gitlab-ci-multi-runner
Login to Gitlab.com and navigate to the project you want to use the runner for. Open the project
Settings -> CI/CD Pipelines section.
You will then see the
Specific Runners section which contains the URL and key to use to setup your runner.
Register the runner
When asked which exector to use, type in
docker. You will need to provide the default docker image to use, I used
elixir:1.4. Also I set the runner to not be project specific, and to only run tagged builds. The tag I am using for the runner is
Configure your Elixir application
.gitlab-ci.yml file, at the root of your repo, with the following contents.
image: elixir:1.4 services: - postgres:9.6.2 variables: POSTGRES_DB: project_test POSTGRES_USER: runner POSTGRES_PASSWORD: “s0m3P@ssw0Rd” stages: - test before_script: - mix local.hex –force - mix local.rebar –force - mix deps.get - MIX_ENV=test mix ecto.create - MIX_ENV=test mix ecto.migrate unit-testing: stage: test script: - MIX_ENV=test mix test tags: - elixir
image– Define what Docker image (from Docker Hub) the environment will run on. I chose elixir:1.4 which provides an environment running Erlang 19 and Elixir 1.4.2 (at the time of writing).
services– Secondary services our environment requires. Checkout the Gitlab Docker Services documentation for more information. For my use case, I only need Postgresql 9.6.2. This is also a Docker container from Docker Hub.
variables– This section is where you setup the credentials for the Postgresql server. Public repos will want to set the ENV vars within the Pipeline settings so they don’t expose their credentials. I have not tested that, and my repo is private, I added them directly in the config. The Elixir applications database configuration will need to match the Postgresql credentials that are setup within
.gitlab-ci.ymlor ENV vars.
stages– Gitlab has three stages in their CI/CD process. I am only going to use
testfor now, but the other two are
deploy. I would like to get CD working at some point, so keep an eye out for a post covering deployment.
before_script– Commands to execute before any jobs are ran. The application has dependencies that need to install in order to run tests. Hex/Rebar must be installed locally and
--forceis used as it is ran in non-interactive mode. After that use mix to install the dependencies for the application. Finally use ecto to create and migrate the database.
unit-testing– This is the name of the job as it will show up within Gitlab CI. You can name your job as you see fit. This example is pretty small, so checkout the Gitlab docs for more details. The job is going to be executed during the
teststage (recall the three stages listed above, this is how you scope jobs to stages). To actually execute the tests, the commands contained within the
scriptsection are ran. The
MIX_ENVmust be set to
testto ensure proper scoping to the test env (testing database configuration is used). The tests are executed using the
mix testcommand. Lastly the
elixirtag is added to the job, this matches the tag used during runner setup, and allows the runner to execute this job.
The last step before any tests can be ran is to update the
config/test.exs file. The database name, username, password, and host should match what was set in the
.gitlab-ci.yml file. We didn’t explicitly set the host in that file because it is handled for us. The hostname would be
# Configure your database (config/test.exs) config :project, Project.Repo, adapter: Ecto.Adapters.Postgres, username: "runner", password: "s0m3P@ssw0Rd", database: "project_test", hostname: "postgres", pool: Ecto.Adapters.SQL.Sandbox
Push the branch to Gitlab, and open the
Pipeline tab for the project. You should see the tests running for your branch. The page doesn’t appear to automatically update, a refresh may be needed to see latest pushes. If the tests pass, you should see something similar:
Gitlab also has badges build in to spice up your README or project site.
May 5th 2017– Added which exector to use during runner setup.