Operations grimoire/Alkane: Difference between revisions
(Created page with "'''Alkane''' is the new codename for our platform to host PHP and static websites. Alkane servers offer: * nginx to serve static content directly and proxy other requests * php-fpm to serve PHP content We maintain a state-of-art installation in the continuity of our shared hosting expertise: up-to-date PHP versions, dedicated site users for privilege separations, custom PHP pools. Sites are published to Alkane by a Jenkins job running on CD. Again for privilege separ...") |
(.env documentation) |
||
(5 intermediate revisions by the same user not shown) | |||
Line 11: | Line 11: | ||
Alkane is a work in progress to track at [https://devcentral.nasqueron.org/T1803 T1803]. | Alkane is a work in progress to track at [https://devcentral.nasqueron.org/T1803 T1803]. | ||
== Why Alkane? == | == Guides == | ||
=== Host a new site === | |||
==== DNS ==== | |||
'''Production.''' subdomain.domain.tld CNAME www-alkane.nasqueron.org | |||
'''Devserver.''' subdomain.domain.tld CNAME www-dev.nasqueron.org | |||
==== nginx ==== | |||
* In {{Ops file|pillar/paas/alkane/web-001/}} add the subdomain in nginx_vhosts | |||
* In {{Ops file|roles/webserver-alkane/nginx/files/vhosts/}} add the nginx configuration file | |||
==== Auto-provisioning ==== | |||
;Through Jenkins: | |||
* A CD job to deploy specific releases or your last commit | |||
* Nothing fancy? You can adopt a standard job template "git fetch --all && git switch <new tag>" or the job "ensure you're on main then git pull" | |||
** But beware to trap like Laravel cache clearing, databases migrations | |||
* Jenkins build scripts can be ported to Dockerfile if you prefer to host the PHP site on our Docker PaaS | |||
;Through Salt: | |||
{{Ops file|roles/webserver-content}} can provision configuration for your site, especially if you need content elsewhere than in /var/wwwroot/<domain.tld>/<sub> (that content is for Jenkins to provision) | |||
==== Database ==== | |||
'''PostgreSQL.''' Hosted on db-A cluster, see [[Operations grimoire/PostgreSQL]] | |||
'''MySQL.''' Hosted on db-B cluster, see [[Operations grimoire/MySQL]] | |||
'''Redis/memcached/etc.''' There are fully supported. For more complex applications, there are two roads: | |||
* (i) the Docker PaaS, look for example how are deployed Airflow, Sentry and Penpot stacks; | |||
* (ii) we create role/saas-<app> and we look if it's suitable for Alkane or if we create a specific server for that app. | |||
We're here to help, create a task on DevCentral with your ideas and we can offer architecture guidance and tips to host it in the best conditions. | |||
=== Provision credentials with .env === | |||
You can use the <code>webserver_content_dotenv</code> pillar to generate .env files. | |||
Those files allow sites using libraries like DotEnv to read secrets. | |||
To ensure secrets can only be read by application user, use: | |||
user: <php-fpm pool user> | |||
If your configuration can be read and stored in memory, | |||
it's probably best to directly call Vault from the app | |||
and only provision Vault AppRole credentials: | |||
vault: <path to AppRole credential> | |||
For PHP sites where the configuration file is read every | |||
request, it's probably best to cache secrets in file | |||
through this mechanism. | |||
If you need a database, you can use: | |||
db: | |||
service: entry in nasqueron_services table | |||
credentials: path to Vault secret | |||
To provision a secret key or other credentials, use: | |||
extra_credentials: | |||
key: path to vault secret | |||
If you need to pass extra plain values use: | |||
extra_values: | |||
key: value | |||
=== Migrate from Ysul === | |||
A small checklist: | |||
* Secrets should be stored on Vault | |||
** As a migration path or alternative, you can use rOPS to provision files from Vault content | |||
** Database user must be declared to {{Ops file|pillar/dbserver/cluster-B.sls}} (and Vault) | |||
** You can use a PHP Vault SDK to read it and ask {{Ops file|roles/webserver-content}} to generate AppRole information for your site | |||
* Build instructions should be moved from {{Ops file|roles/webserver-content}} to a Jenkinsfile on your repository | |||
* Access to Docker resources should use private network | |||
== Why the name Alkane? == | |||
Oh, it's a word Dereckson thought about while thinking about a new webserver-<word> to replace webserver-legacy. | Oh, it's a word Dereckson thought about while thinking about a new webserver-<word> to replace webserver-legacy. | ||
Line 29: | Line 109: | ||
Alkane, with its connotations of stability and simplicity, could reflect the value of elegance and simplicity that Nasqueron promotes. Meanwhile, Pulse, with its connotations of speed and responsiveness, could reflect the values of innovation and continuous improvement that Nasqueron also promotes. | Alkane, with its connotations of stability and simplicity, could reflect the value of elegance and simplicity that Nasqueron promotes. Meanwhile, Pulse, with its connotations of speed and responsiveness, could reflect the values of innovation and continuous improvement that Nasqueron also promotes. | ||
Latest revision as of 20:51, 27 June 2023
Alkane is the new codename for our platform to host PHP and static websites.
Alkane servers offer:
- nginx to serve static content directly and proxy other requests
- php-fpm to serve PHP content
We maintain a state-of-art installation in the continuity of our shared hosting expertise: up-to-date PHP versions, dedicated site users for privilege separations, custom PHP pools.
Sites are published to Alkane by a Jenkins job running on CD. Again for privilege separation, Jenkins uses different containers per site to build the site artefact.
Alkane is a work in progress to track at T1803.
Guides
Host a new site
DNS
Production. subdomain.domain.tld CNAME www-alkane.nasqueron.org
Devserver. subdomain.domain.tld CNAME www-dev.nasqueron.org
nginx
- In rOPS: pillar/paas/alkane/web-001/ add the subdomain in nginx_vhosts
- In rOPS: roles/webserver-alkane/nginx/files/vhosts/ add the nginx configuration file
Auto-provisioning
- Through Jenkins
- A CD job to deploy specific releases or your last commit
- Nothing fancy? You can adopt a standard job template "git fetch --all && git switch <new tag>" or the job "ensure you're on main then git pull"
- But beware to trap like Laravel cache clearing, databases migrations
- Jenkins build scripts can be ported to Dockerfile if you prefer to host the PHP site on our Docker PaaS
- Through Salt
rOPS: roles/webserver-content can provision configuration for your site, especially if you need content elsewhere than in /var/wwwroot/<domain.tld>/ (that content is for Jenkins to provision)
Database
PostgreSQL. Hosted on db-A cluster, see Operations grimoire/PostgreSQL
MySQL. Hosted on db-B cluster, see Operations grimoire/MySQL
Redis/memcached/etc. There are fully supported. For more complex applications, there are two roads:
- (i) the Docker PaaS, look for example how are deployed Airflow, Sentry and Penpot stacks;
- (ii) we create role/saas-<app> and we look if it's suitable for Alkane or if we create a specific server for that app.
We're here to help, create a task on DevCentral with your ideas and we can offer architecture guidance and tips to host it in the best conditions.
Provision credentials with .env
You can use the webserver_content_dotenv
pillar to generate .env files.
Those files allow sites using libraries like DotEnv to read secrets.
To ensure secrets can only be read by application user, use:
user: <php-fpm pool user>
If your configuration can be read and stored in memory, it's probably best to directly call Vault from the app and only provision Vault AppRole credentials:
vault: <path to AppRole credential>
For PHP sites where the configuration file is read every request, it's probably best to cache secrets in file through this mechanism.
If you need a database, you can use:
db: service: entry in nasqueron_services table credentials: path to Vault secret
To provision a secret key or other credentials, use:
extra_credentials: key: path to vault secret
If you need to pass extra plain values use:
extra_values: key: value
Migrate from Ysul
A small checklist:
- Secrets should be stored on Vault
- As a migration path or alternative, you can use rOPS to provision files from Vault content
- Database user must be declared to rOPS: pillar/dbserver/cluster-B.sls (and Vault)
- You can use a PHP Vault SDK to read it and ask rOPS: roles/webserver-content to generate AppRole information for your site
- Build instructions should be moved from rOPS: roles/webserver-content to a Jenkinsfile on your repository
- Access to Docker resources should use private network
Why the name Alkane?
Oh, it's a word Dereckson thought about while thinking about a new webserver-<word> to replace webserver-legacy.
Meanwhile, ChatGPT suggested "pulse" among other uninspired names.
Some fun about what ChatGPT has to say about Alkane:
Alkane could be a good product name for a webserver distribution for PHP and static sites. The name "Alkane" is a chemical term that refers to a type of hydrocarbon molecule that is characterized by its stability and simplicity. This name could be interpreted to mean that the webserver distribution is stable and easy to use. Additionally, the name "Alkane" has a unique and memorable sound, which could help the product stand out in a crowded market. The name is also short and easy to spell, which could make it easy to remember and type into search engines. ______ Alkane, with its connotations of stability and simplicity, could be a good fit for a PaaS that offers a reliable and user-friendly hosting experience. The name also has a technical-sounding quality that could resonate with developers and IT professionals who are familiar with the concept of hydrocarbons in chemistry.
Both Alkane and Pulse are aligned with Nasqueron values:
Alkane, with its connotations of stability and simplicity, could reflect the value of elegance and simplicity that Nasqueron promotes. Meanwhile, Pulse, with its connotations of speed and responsiveness, could reflect the values of innovation and continuous improvement that Nasqueron also promotes.