Operations grimoire/Sites on Ysul

From Nasqueron Agora


Sites on Ysul are deployed to /var/wwwroot.

Four processes are known:

  • through custom deployment script (e.g. Zed, Nasqueron Tools)
  • through Git (e.g. www.espace-win.org archive)
  • through Jenkins task (e.g. dæghrefn.nasqueron.org)
  • without any deployment workflow

Deploy through Salt

Ysul has the webserver-legacy role.

By legacy, we mean you don't deploy the site as a container, but use the traditional workflow.


Drop the nginx configuration in the roles/webserver-legacy/nginx/files/vhosts folder.

You're encouraged to tweak nginx configuration to handle a maximum of features through the web server, and not all in your web app code. Note the lua module isn't active there (but we could enable it).


If you want to serve a PHP site, you need:

  • a unix account for the PHP application
  • a php-fpm pool configuration
  • at least one block block to call php-fpm

To get all of that, you can follow this procedure:

  1. seek to pillar/webserver/sites.sls the web_php_sites block, and add your site:
    1. Use web-be-domain-sub as user, excepted if you need to divide a subdomain into several independent apps for better security
    2. If you want to deploy from the staging repository, specify source (the path relative to the staging repo) and target (the absolute path on the server): they normally should be wwwroot/domain.tld/sub and /var/wwwroot/domain.tld/sub
    3. If you've a more complex deployment logic than just copy code from a repo, see custom content deployment section and don't specify source or target here
    4. If your application follows https://12factor.net/config, specify the environment as an hashmap in the env parameter. Never store credentials in the rOPS repository, this is a public one.
    5. By default, PHP errors are logged on file,
  2. edit the nginx configuration in roles/webserver-legacy/nginx/files/vhosts:
    1. Your proxy_pass address should be unix:/var/run/web/<subdomain>.<domain>/php-fpm.sock
    2. You probably want to get generic FastCGI headers with include includes/fastcgi_params;.
  3. Deploy or ask to deploy the acccount part: salt-call --local state.apply roles/webserver-legacy/php-sites/account
  4. Deploy or ask to deploy the php-fpm part: salt-call --local state.apply roles/webserver-legacy/php-sites/php-fpm
  5. Deploy or ask to deploy the nginx part: salt-call --local state.apply roles/webserver-legacy/nginx
  6. Reload nginx and php-fpm

For example, www.wolfplex.org uses the following block (for misc scripts, not for the wiki):

   location ~ \.php$ {
       fastcgi_pass unix:/var/run/web/www.wolfplex.org/php-fpm.sock;
       fastcgi_index index.php;
       fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
       include includes/fastcgi_params;

Static sites standard deployment

If your repository is an already built and ready site, you can add it to rOPS: pillar/webserver/sites.sls in the web_static_sites dictionary.

It's then easy to deploy it through the static-sites unit:

   salt-call --local state.sls_id /var/wwwroot/nasqueron.org/launch roles/webserver-legacy/static-sites

This only deploy content. It also needs a nginx configuration.

Custom content deployment

Set the instructions to deploy your site in the roles/webserver-content/ folder:

If your website is www.acme.tld, you should create:

  • roles/webserver-content/tld/acme/init.sls to include www file
  • roles/webserver-content/tld/acme/www.sls with the deployment logic

The webserver-content role belongs to EVERY web servers, not only Ysul. You so need to filter where it should be deployed:

  • in your <subdomain>.sls files, embed the logic in a if block: {% if salt['node.has_web_content'](".tld/acme/www") %} and {% endif %}.
  • in the pillar configuration, edit pillar/webserver/sites.sls and add your site to the web_content_sls: use subdomain if you want better flexibility or domain if you're sure to want to group everything on one role. You only need to map this value with the value used in the if block, as node.has_web_content argument.

Automatic deployment on commit to master

This procedure is currently restricted to static content sites.

A compilation step managed by grunt, gulp, etc. is acceptable.

To deploy a Jenkins-powered site, just commit to master and the deploy job will run automatically:

  • assets.nasqueron.org
  • autoconfig.nasqueron.org
  • daeghrefn.nasqueron.org
  • docker.nasqueron.org
  • launch.nasqueron.org
  • www.nasqueron.org

To allow a new site to be deployed like this:

$ chown -R alken-orin:nasqueron /var/wwwroot/nasqueron.org/subdomain
$ sudo -u alken-orin ln -s /var/wwwroot/nasqueron.org/subdomain subdomain.nasqueron.org

On Jenkins create a new item deploy-website-nasqueron-www1-subdomain from the deploy-website-nasqueron-www1-assets template.

On DevCentral or GitHub, create a herald rule or webhook to warn Jenkins there is a new commit.

Other sites

For other sites, reach Dereckson for guidance and support.


There are three php-fpm pools available.

Name Version Configuration Location
Prod PHP 7.2 /usr/local/etc/php.ini Installed through php72- packages.
Dev PHP 7.x /usr/local/etc/php-dev.ini /opt/php (To install if needed)
Legacy PHP 5.6 /usr/local/etc/phi.ini To install if needed