forked from data.coop/ansible
Merge pull request 'Add README.md' (#127) from readme into main
Reviewed-on: data.coop/ansible#127
This commit is contained in:
commit
97e5f264f9
105
README.md
Normal file
105
README.md
Normal file
|
@ -0,0 +1,105 @@
|
|||
# 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
|
||||
Ansible playbook uses two custom-made roles (in the `roles/` directory):
|
||||
|
||||
- `ubuntu_base` - used to configure the host itself and install the
|
||||
necessary packages
|
||||
- `docker` - used to deploy our services and websites with Docker
|
||||
containers
|
||||
|
||||
The script has options to deploy only one of the roles. Select services
|
||||
only can also be specified. By default, the script deploys everything.
|
||||
|
||||
Here is a summary of the options that can be used with the script:
|
||||
|
||||
```sh
|
||||
# deploy everything
|
||||
./deploy.sh
|
||||
|
||||
# deploy the ubuntu_base role only
|
||||
./deploy.sh base
|
||||
|
||||
# deploy the docker role only
|
||||
./deploy.sh services
|
||||
|
||||
# deploy SINGLE_SERVICE Docker service only
|
||||
./deploy.sh services SINGLE_SERVICE
|
||||
```
|
||||
|
||||
`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`).
|
||||
|
||||
## 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:
|
||||
|
||||
```sh
|
||||
# Create and provision the VM
|
||||
vagrant up
|
||||
|
||||
# Re-provision the VM
|
||||
vagrant provision
|
||||
|
||||
# SSH into the VM
|
||||
vagrant ssh
|
||||
|
||||
# Power down the VM
|
||||
vagrant halt
|
||||
|
||||
# Power down and delete the VM
|
||||
vagrant destroy
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```sh
|
||||
# deploy the ubuntu_base role only in the Vagrant VM
|
||||
./deploy.sh --vagrant base
|
||||
|
||||
# deploy SINGLE_SERVICE Docker service only in the Vagrant VM
|
||||
./deploy.sh --vagrant services SINGLE_SERVICE
|
||||
```
|
||||
|
||||
Note that the `--vagrant` flag should be the first argument when using
|
||||
the script.
|
||||
|
||||
## 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:
|
||||
|
||||
```sh
|
||||
make init
|
||||
```
|
||||
|
||||
## Nice tools
|
||||
|
||||
- [J2Live](https://j2live.ttl255.com/): A live Jinja2 parser, nice to
|
||||
test out filters
|
||||
|
Loading…
Reference in a new issue