Local builds using Docker
The main concept in Fire CI is that your CI builds are run on your computer inside Docker containers. The Docker layer completely abstracts the build from your native system.
Fire CI has been built with Docker, git and GitHub as an ecosystem:
What is needed for Fire CI to run on your computer?
The Fire CI agent needs git and Docker. That's it. We currently support Windows and Mac. A Linux version of the agent is on the way. Installation runs as a simple .exe file for Windows and .pkg file for Mac.
The check for git and docker installation is made by the agent when you install it. If anything is missing the agent will tell you what exactly so you don't have to fumble around.
To download the agent you need to signup to Fire CI using your GitHub account. It will generate a code to pair the agent to your account and that's it.
How do I tell GitHub to notify Fire CI?
GitHub has a concept called "GitHub Apps". We have our GitHub App called "Fire CI" that you can add via the GitHub UI to all or part of your repositories. You can choose your personal or your organization's repositories.
The GitHub App is the mean that GitHub uses to know that it needs to notify the Fire CI servers when new code is pushed. The notifications contain the branch, the sha of the commit and the author of the pushed code. The Fire CI servers will then pick the agent paired to the code author's account so it runs the build.
The configuration of the repositories Fire CI can be notified about is fully done and secured by GitHub. The installation of our GitHub app and selection of your repositories is part of the agent installation when you run it the first time.
How are builds defined?
How do I tell Fire CI how the builds need to be run? Which commands to execute? In which order?
Fire CI provides 3 ways of defining builds.
- YAML files: Builds can be defined using YAML files. This covers most of the use cases you might have and provides smart caching for your builds to run faster. See Using YAML files.
- Dockerfile: If the YAML format does not allow to do what you want, you can write your raw Dockerfile and it will be executed by the agent using a docker build command. If the exit code of the commands in the Dockerfile is 0 the build will be considered as success, and error otherwise. This is as flexible as it gets but you need to know a few things about Docker and how to write Dockerfiles. Here is the reference documentation and the best practices. You can contact us if you have questions. We'll be glad to help you.
- Docker Compose: Docker compose allows you to run multiple containers, link networks and volumes between them, and thus create complex builds. Fire CI can run a docker-compose.yml file and will use the exit code of the first exiting container as result of the build (0 meaning success). This kind of build is useful for end to end testing where you can run a database in one container, your running API in another, and hit the API with your end to end tests from yet another container. See the reference documentation of docker compose and our tutorial for API end to end testing.
How do I see build results and logs?
The Fire CI agent runs in the background of your computer. It's only UI is a tray icon that changes color when a build is running, success or error. The agent also notifies you via desktop notifications when a build starts and ends. You can disabled part or all notifications if you want. The tray during a build in a progress and after a succesfull build look like this on Mac:
When a build runs you can track the logs in real time in a local window displayed by the agent. The build status, current step and logs are pushed to GitHub in real time and the build can also be tracked there.
The GitHub builds history shows the status of each build and result for each step:
Clicking on the details of a given step will take you to the detailed page of the build where you can see:
- The status for each build step (and more importantly which one failed if any)
- The time each step took ("less than 20 seconds" in the example below)
- The full logs for each step: the GitHub API available to provide this feature has some limitations in size and if your logs are very long they won't be fully visible in the GitHub UI. You'd have to have very verbose builds to get there though! Anyway, we also provide a link to download raw logs in case this happens.
You can read the two articles below:
We are striving for an intuitive and turn key setup so you can already signup and follow the agent installation process. Documentation might not be that needed after all.
If you have questions or ideas do not hesitate to contact us at firstname.lastname@example.org.