Adding a Website

Copy the site-template.yml (again we’ll assume your server is called alice) in host_vars/alice/websites/ to a file matching the name of your web site. Use a succinct name as this will be used to create an nginx vhost, root directory and Forgejo git repository of the same name.

Using a website named myblog as an example:

cp site-template.yml myblog.yml

Edit myblog.yml and add the full web site domain name and whatever other options are appropriate – the template is largely self documenting, uncomment options if needed. You may also change or remove all comments, simply refer back to the site-template.yml file if needed.

By default the settings has_stage and is_enabled are set such that only a staging site is created. If you want to also add the production site now make sure the domain is pointing at and resolving to your server’s IP address before you run the websites play.

In Forgejo a repository can be created with a user or an organization as the owner. If you set repo_owner to an organization then be sure to set repo_owner_is_org to true.

Run the websites play, you probably want to limit this to a group of servers or a single server in your hosts.ini:

ansible-playbook  --ask-vault-pass --limit YOURSERVER play/websites.yml

Be patient, especially on the first run. The website role will set up, using our example site named myblog and assuming has-stage is set true:

  • Site roots in /var/www/myblog and /var/www/myblog-stage
  • Nginx vhost files in /etc/nginx/sites-available, both myblog.conf and myblog-stage.conf
  • A Git repository ‘myblog’ in Forgejo. It will also add a git post-recieve script to the Forgejo repository.

The post-recieve script will deploy code committed to staging or production branches to the respective web root. It’s important that you create those branches with those exact names.

Hugo sites will be built and then deployed. If you use my HuMC script to create your site it will automatically add staging and production branches which you then need to push to the Forgejo repository.

All staging sites are protected by nginx basic auth using the user and pass defined in your host_vars (Websites section, staging_user_password variable).

Per site authentication eg .htpasswd-myblog will also be added if defined in the per site vars.

Once the play has finished you should be able to visit defined websites at their respective URL, and staging sites at eg myblog.stage.example.com. These will of course be empty until you commit code to the staging or production branches of the repository!

The websites role should be re-run whenever you change these per site vars file to propagate the changes.

Note – There is currently no way pass an individual site to the websites play/role so the role will iterate over ALL defined sites on each run. This gets very slow and tedious with more than a handful of web sites defined. I’ve yet to figure out a way around this. Submit an issue if you have suggestions!

However, adding or removing web sites is a relatively rare operation and the git based deploy method Momod configures makes deploying updates fast and painless.