Skip to content
Snippets Groups Projects
README.md 5.68 KiB
Newer Older
Dennis Ahrens's avatar
Dennis Ahrens committed
# deploy-formula
Dennis Ahrens's avatar
Dennis Ahrens committed

Dennis Ahrens's avatar
Dennis Ahrens committed
Deploy code!

## users

The deployment runs as `root`, which has access to e.g. gitlab.
Dennis Ahrens's avatar
Dennis Ahrens committed
The formula is organized in projects.

```yaml
deploy:
  projects:
    project_name: {}
```

For each project an additional user with the name `project_name` gets created.
Dennis Ahrens's avatar
Dennis Ahrens committed
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.

Fynn Becker's avatar
Fynn Becker committed
### `deploy.certs`
Dennis Ahrens's avatar
Dennis Ahrens committed

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`

Fynn Becker's avatar
Fynn Becker committed
This combines `deploy.bundle.django`, `deploy.certs`, `nginx` and `uwsgi`.
Dennis Ahrens's avatar
Dennis Ahrens committed
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.

```yaml
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.

Dennis Ahrens's avatar
Dennis Ahrens committed
- `deploy.config.key` **no default value**
Dennis Ahrens's avatar
Dennis Ahrens committed
  A private key that is able to access repositories.
  **Deprecated** Use [gitlab deploy tokens](https://doc.it.hs-hannover.de/books/sysadmin/page/gitlab-deploy-with-token-and-without-ssh) instead:
Dennis Ahrens's avatar
Dennis Ahrens committed
- `deploy.config.deploy_directory` _default: `/srv/repo`_
Dennis Ahrens's avatar
Dennis Ahrens committed
  The directory in which git clones are located.
Dennis Ahrens's avatar
Dennis Ahrens committed
- `deploy.config.venv_directory` _default: `/srv/venv`_
Dennis Ahrens's avatar
Dennis Ahrens committed
  The directory in which virtualenvs are located.
Dennis Ahrens's avatar
Dennis Ahrens committed
- `deploy.config.cert_directory` _default: `/etc/hsh-certs`_
Dennis Ahrens's avatar
Dennis Ahrens committed
  The directory in which certificates are located.
Dennis Ahrens's avatar
Dennis Ahrens committed
- `deploy.config.static_directory` _default: `/srv/static`_
Dennis Ahrens's avatar
Dennis Ahrens committed
  Static files related settings that are magically set by the `deploy.django` state.
Dennis Ahrens's avatar
Dennis Ahrens committed
- `deploy.config.static_url` _default: `https://static.it.hs-hannover.de`_
Dennis Ahrens's avatar
Dennis Ahrens committed
  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).

```yaml
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.
Fynn Becker's avatar
Fynn Becker committed
Only describing e.g. `cert` for a project without applying the corresponding state `deploy.certs` does not roll our your cert.
Dennis Ahrens's avatar
Dennis Ahrens committed

#### `deploy.projects.[...].gitlab`

Dennis Ahrens's avatar
Dennis Ahrens committed
- `url` **no default**
Dennis Ahrens's avatar
Dennis Ahrens committed
  The URL to clone from.
Dennis Ahrens's avatar
Dennis Ahrens committed
- `rev` **no default**
Dennis Ahrens's avatar
Dennis Ahrens committed
  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.

Dennis Ahrens's avatar
Dennis Ahrens committed
- `requirements` _default: `project_path/requirements.txt`_
Dennis Ahrens's avatar
Dennis Ahrens committed
  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`

Dennis Ahrens's avatar
Dennis Ahrens committed
- `collectstatic` _default: `False`_
Dennis Ahrens's avatar
Dennis Ahrens committed
  If true the deployment runs `./manage.py collectstatic`
Dennis Ahrens's avatar
Dennis Ahrens committed
- `migrate` _default: `False`_
Dennis Ahrens's avatar
Dennis Ahrens committed
  If true the deployment runs `./manage.py migrate`
Dennis Ahrens's avatar
Dennis Ahrens committed
- `settings_path` _default: `project_path/project_name/settings/prod.py`_
Dennis Ahrens's avatar
Dennis Ahrens committed
  The path where to write the django settings to.
Dennis Ahrens's avatar
Dennis Ahrens committed
- `settings` **no default**
Dennis Ahrens's avatar
Dennis Ahrens committed
  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: `[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.
Dennis Ahrens's avatar
Dennis Ahrens committed

### `deploy.certs`

Each cert may have the following fields:

Dennis Ahrens's avatar
Dennis Ahrens committed
- `pem` **required**
Dennis Ahrens's avatar
Dennis Ahrens committed
  The X.509 certificate.
Dennis Ahrens's avatar
Dennis Ahrens committed
- `key` **required**
Dennis Ahrens's avatar
Dennis Ahrens committed
  The key for the certificate.
Dennis Ahrens's avatar
Dennis Ahrens committed
- `chain`
  The certificate chain - usually without the root certificate.
Dennis Ahrens's avatar
Dennis Ahrens committed
- `cacert`
  The root certificate - this is usually not necessary, except you roll out your own PKI.
Dennis Ahrens's avatar
Dennis Ahrens committed
- `dhparam`
Dennis Ahrens's avatar
Dennis Ahrens committed
  The diffie hellman parameter.

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

Dennis Ahrens's avatar
Dennis Ahrens committed
- `certname.pem`
- `certname.key`
- `certname.chain.pem`
- `certname.cacert.pem`
- `certname.dhparam.pem`
- `certname.fullchain.pem`
Dennis Ahrens's avatar
Dennis Ahrens committed
  `pem` + `chain`
Dennis Ahrens's avatar
Dennis Ahrens committed
- `certname.fullchain.dhparam.pem`
Dennis Ahrens's avatar
Dennis Ahrens committed
  `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.