Here we list regular actions or configuration that might be needed and is not simple such as certificates handling or operations in production.
HTTPS Cert Resolvers
Lokal provides a few ways of allowing HTTPS. You need SSL certificates for your domain to be able to use HTTPS protocol. Lokal uses traefik for routing thus we are using its capabilities.
The simplest method for obtaining certificates from Let's Encrypt is using the HTTP challenge. Before you use this, you need to prepare your DNS A entries to point to your Lokal server. In your hosts file, make sure to have those variables.
email_admin: email@example.com ssl_use_acme: true cert_resolver: http
Your email is necessary for registering to Let's encrypt.
on the usage of Let's Encrypt and cert_resolver to http is obvious in this case.
Traefik will generate one certificate for each subdomain that any of your application uses. It even handles automatic renewal before expiration.
DNS challenge still uses Let's Encrypt but it doesn't require you to pre-set your DNS records. Since somebody has to do it, then your DNS provider must support API access and traefik handles this. Currently, the only supported DNS provider is Namecheap. Following variables are necessary in the hosts file.
email_admin: firstname.lastname@example.org ssl_use_acme: true cert_resolver: dns dns_provider: namecheap namecheap_api_user: your-user namecheap_api_key: your-key
Suppose you have set your domain's DNS to your Lokal server IP and you have a
wildcard certificate and matching key for your domain. Simply specify them as
CWD where you are running the main playbook from.
ssl_cert: "hosts/<my-domain>.crt" ssl_key: "hosts/<my-domain>.key"
If you don't setup
ssl_cert then this is the
default option. The disadvantage is, that your temporal certificate authority
will definitely not be trusted by browsers. Therefore anybody accessing any
Lokal services will get "Invalid certificate" warning and must confirm security
exception for every domain separately.
Operations describe management during the full lifetime of Lokal. In general, you will want to perform - upgrade - backup - restore - remove
All of those commands are supported by
playbook.yml and their support should be
included in every role (service).
Roles should be written in such ways that the installation should behave as an upgrade
if it is run on already installed service. Usually, there are no extra steps required
than simply downloading a new docker image and restarting the service. Surely, you
want to upgrade services one-by-one, therefore we included
install variable to
let you do exactly that. Following command will install/upgrade only the specified
ansible-playbook -i hosts/<your-host-file> -e install=wordpress,matmoto playbook.yml
You can either backup concrete services by specifying
ansible-playbook -i hosts/<your-host-file> -e backup=wordpress,matmoto playbook.yml
Of course you can restore backed up services using
ansible-playbook -i hosts/<your-host-file> -e restore=wordpress playbook.yml
For uninstallation we provide
-e remove=service1,service2 variable.
ansible-playbook -i hosts/<your-host-file> -e remove=wordpress playbook.yml