datacoop.ansible/README.md

87 lines
3.1 KiB
Markdown
Raw Normal View History

2022-11-25 22:31:30 +00:00
# data.coop infrastructure
This repository contains the code used to deploy data.coop's services
and websites. We use Ansible to encode our infrastructure setup. Only
the association's administrators have access to deploy the services.
## Deploying
To deploy the services, the included `deploy.sh` script can be used. The
2022-11-28 17:20:12 +00:00
Ansible playbook uses two custom-made roles (in the `roles/` directory):
2022-11-28 17:56:09 +00:00
- `ubuntu_base` - used to configure the host itself and install the
2022-11-28 17:20:12 +00:00
necessary packages
- `docker` - used to deploy our services and websites with Docker
containers
2022-11-28 17:56:09 +00:00
The script has options to deploy only one of the roles. Select services
only can also be specified. By default, the script deploys everything.
2022-11-25 22:31:30 +00:00
2022-11-26 15:32:06 +00:00
Here is a summary of the options that can be used with the script:
2022-11-25 22:31:30 +00:00
```console
2022-11-26 15:32:06 +00:00
$ ./deploy.sh # deploy everything
$ ./deploy.sh base # deploy the ubuntu_base role only
$ ./deploy.sh services # deploy the docker role only
$ ./deploy.sh services SINGLE_SERVICE # deploy SINGLE_SERVICE Docker service only
2022-11-25 22:31:30 +00:00
```
2022-11-27 16:20:40 +00:00
`SINGLE_SERVICE` should match one of the service names in the `services`
dictionary in `roles/docker/defaults/main.yml` (e.g. `gitea` or
`data_coop_website`).
2022-11-25 22:31:30 +00:00
## Testing
In order for us to be able to test our setup locally, we use Vagrant to
deploy the services in a virtual machine. To do this, Vagrant and
VirtualBox must both be installed on the development machine. Then, the
services can be deployed locally by using the `vagrant` command-line
tool. The working directory needs to be the root of the repository for
this to work properly.
> Note: As our secrets are contained in an Ansible Vault file, only the
> administrators have the ability to run the deployment in Vagrant.
> However, one could replace the vault file for testing purposes.
Here is a summary of the commands that are available with the `vagrant`
command-line tool:
```console
2022-11-25 22:31:30 +00:00
$ vagrant up # Create and provision the VM
$ vagrant provision # Re-provision the VM
$ vagrant ssh # SSH into the VM
$ vagrant halt # Power down the VM
$ vagrant destroy # Power down and delete the VM
```
2022-11-26 15:32:06 +00:00
The `vagrant` command-line tool does not support supplying extra
variables to Ansible on runtime, so to be able to deploy only parts of
the Ansible playbook to Vagrant, the `deploy.sh` script can be used with
the `--vagrant` flag. Here are some examples:
```console
2022-11-26 15:32:06 +00:00
$ ./deploy.sh --vagrant base # deploy the ubuntu_base role only in the Vagrant VM
$ ./deploy.sh --vagrant services SINGLE_SERVICE # deploy SINGLE_SERVICE Docker service only in the Vagrant VM
```
Note that the `--vagrant` flag should be the first argument when using
the script.
2022-11-28 18:24:49 +00:00
## Contributing
If you want to contribute, you can fork the repository and submit a pull
request. We use a pre-commit hook for linting the YAML files before
every commit, so please use that. To initialize pre-commit, you need to
have Python and GNU make installed. Then, just run the following shell
command:
```console
$ make init
```
2022-11-26 21:50:32 +00:00
## Nice tools
- [J2Live](https://j2live.ttl255.com/): A live Jinja2 parser, nice to
test out filters