π° Paid add-ons. The modules
basis,monitoring-client,monitoring-serverandproxyneed a Pro or higher license from starter-kit.io. Without a license,kit-modules/is empty and this page does not apply. Already purchased? See Quick start after purchase.
Terraform and Ansible ship inside the basis module, which Composer installs once a license is
configured (see Composer usage).
For an interactive shell inside the IaC container, already cd‘d into kit-modules/basis, run:
make basis
Setup infrastructure with Terraform
Terraform provisions the cloud infrastructure in three steps. Run them in this order, because each step uses the result of the one before:
stateβ creates the S3 bucket that stores Terraform state. No lock table is needed.sharedβ creates the network (VPC) and uploads your deploy SSH public key.devorprodβ creates the server (EC2 instance) for that environment.
Before running Terraform locally, set up two things:
- AWS credentials. Add
AWS_ACCESS_KEY_IDandAWS_SECRET_ACCESS_KEY(plusAWS_SESSION_TOKENfor temporary credentials) toconfig/environment/.env.secret, then runmake env <env>; they are passed into theiaccontainer.~/.aws/credentialsis not read. CI uses a short-lived AWS OIDC role instead β see CI/CD Deployments. - Deploy public key. Create it from your private deploy key. The file name comes from
TF_VAR_sk_ssh_key_namein.env.main(it is notid_rsa.pub):
ssh-keygen -y -f <your-private-key> > kit-modules/basis/terraform/public_keys/<APP_NAME>_deploy_key.pub
- CI derives this file from the
SSH_KEYsecret itself.
Always run
make tf <layer> planand review the diff beforemake tf <layer> apply, where<layer>isstate,shared,devorprod.
make tf state apply
make tf shared apply
make tf dev apply # or: make tf prod apply
The GitHub and GitLab provisioning pipelines offer
stageas an environment choice alongsidedevandprod, but reject it: its Terraform environment exists (kit-modules/basis/terraform/envs/stage/), but Ansible has nostagehost inkit-modules/basis/ansible/inventory.yml, so a server would be created that Ansible cannot configure. Onlydevandprodrun end to end.
Automate server apps with Ansible
- Provision the server first (
make tf <env> apply). Ansible connects to the instance Terraform just created. - Generate the inventory from Terraform’s outputs:
make ansible <env> inventory
- Run the playbook:
make ansible <env> playbook
To use a hand-maintained kit-modules/basis/ansible/inventory.yml instead, skip step 2 and run
make ansible dev playbook static.
After that you can run the CI/CD deployment pipelines.
Monitoring
The monitoring-client module forwards container logs to a Loki log server run by
monitoring-server.
- Set
APP_LOKI_ENABLE=1inconfig/environment/.env.type.<env>(shipped as1fordev/prod,0forlocal). - Turn it on or off (
make monworks too):
make monitoring on
make monitoring off
With APP_LOKI_ENABLE=0, make monitoring on does nothing.
Reverse proxy (multi-instance)
The optional proxy module runs a Traefik reverse proxy in front of several project instances on
one host. With APP_MULTI_INSTANCE=1 it also handles HTTPS (see
HTTPS & Local Certificates).
- If
APP_MULTI_INSTANCEis not1and the module is not installed, the commands below do nothing. - If
APP_MULTI_INSTANCE=1and the module is not installed, they fail. Configure a valid license and runcomposer update solidbunch/proxy.
[email protected] make proxy start # ACME_EMAIL is required, no default
make proxy stop
make proxy logs
make proxy deploy [env]