Operations grimoire/Alkane

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.