deploy-formula

Deploy code!

users

The deployment runs as the user deployer, which has access to e.g. gitlab. The formula is organized in projects.

deploy:
  projects:
    project_name: {}

For each project an additional user with the name project_name gets created, which is a member of the group deployer. This user should be used to run daemons.

states

This formula comes with seperate states that work on integrated pillar. This allows us to compose them as need.

deploy.gitlab

Deploy code from gitlab to the server.

deploy.venv

Create a virtualenv for a project.

deploy.django

Writes a prod.py settings file and allows running migrate and collectstatic for a django instance.

deploy.certs

Roll out certificates that you need for the deployment.

bundles

You need to combine states together based on what you want to deploy. Bundles are state files that include the wanted states together. They also include other formulas for you (but you still need to configure them by yourself using pillar).

deploy.bundle.python

Grab code from gitlab and create a virtualenv.

deploy.bundle.django

Grab code from gitlab and create a virtualenv and take care of django settings. Optionally you can enforce migrate and collectstatic.

deploy.bundle.django-service

This combines deploy.bundle.django and systemd.unit. It requires the systemd-formula to be available.

deploy.bundle.django-uwsgi-nginx

This combines deploy.bundle.django, deploy.certs, nginx and uwsgi. It requires the uwsgi-formula and nginx-formula to be available.

pillar

When you decided which states are necessary you need to confgure the states using pillar.

deploy:
  config: {}
  projects: {}
  certs: {}

deploy.config

This part of the pillar provides overall configuration data for the deployments. It usually should not differ between deployments and might be assigned to many minions.

• deploy.config.key no default value A private key that is able to access repositories.
• deploy.config.deploy_directory default: /srv/repo The directory in which git clones are located.
• deploy.config.venv_directory default: /srv/venv The directory in which virtualenvs are located.
• deploy.config.cert_directory default: /etc/hsh-certs The directory in which certificates are located.
• deploy.config.static_directory default: /srv/static Static files related settings that are magically set by the deploy.django state.
• deploy.config.static_url default: https://static.it.hs-hannover.de Static files related settings that are magically set by the deploy.django state.

deploy.projects

This is the heart of this formula. Here you describe your deployment(s).

deploy:
  projects:
    project_name:
      gitlab: {}
      venv: {}
      django: {}
      cert: {}

Projects are a name and the configuration for the corresponsing states. The name is used for several things within the deployment.

NOTE that you need to assign the states properly. Only describing e.g. cert for a project without applying the corresponding state deploy.certs does not roll our your cert.

deploy.projects.[...].gitlab

• url no default The URL to clone from.
• rev no default The branch, tag or commit that should be deployed

The path to the target directory is created by using deploy.config.deploy_directory + / + project_name.

deploy.projects.[...].venv

You may specify venv: True, which leads in default values. Instead of True venv can also be an object.

• requirements default: project_path/requirements.txt The URL to clone from.

The python version is fixed to the servers python3 version. The environment creation runs in the context of the project user.

deploy.projects.[...].django

• collectstatic default: False If true the deployment runs ./manage.py collectstatic
• migrate default: False If true the deployment runs ./manage.py migrate
• settings_path default: project_path/project_name/settings/prod.py The path where to write the django settings to.
• settings no default Specify django settings in yaml - they are written into a file in the project. This fits our django settings approach.

deploy.projects.[...].user_groups

Each project receives a user that should be used to run the project (if it is runnable somehow...). By default this user is member of the groups: deployer, [project_name] and virtualenv. With user_groups you can define additional groups the user should belojng to. This is especially interesting for access to cert data. If your run user needs to read a cert, you might add him into the corresponding group.

deploy.certs

Each cert may have the following fields:

• pem required The X.509 certificate.
• key required The key for the certificate.
• chain The certificate chain - usually without the root certificate.
• cacert The root certificate - this is usually not necessary, except you roll out your own PKI.
• dhparam The diffie hellman parameter.

The states will create a bunch of files in the deploy.config.cert_directory.

• certname.pem
• certname.key
• certname.chain.pem
• certname.cacert.pem
• certname.dhparam.pem
• certname.fullchain.pem pem + chain
• certname.fullchain.dhparam.pem pem + chain + dhparam

There is group created for each certificate based on the name and prefixed with cert-. If your cert is called helloworld this leads to a group called cert-helloworld. Put users that should read them into those groups.