macrominds website

See macrominds/website-lib for more information about the backend lib.

Create a website

Create a new website with composer create-project macrominds/website my-website.

You will be asked, if you want to remove existing VCS: You want to answer Yes.

Generating autoload files
Do you want to remove the existing VCS (.git, .svn..) history? [Y,n]? Y

Adapt the .env file to your needs.

In a local development environment, you typically want APP_ENV=local to expose exception messages and details. In a production environment, you want APP_ENV=production to prevent the exposure of sensitive information.

Run the demo server

In the website root:

php -S localhost:8080 -t ./public/ ./router.php

If you want to make it externally accessible, use the IP address of your machine:

# fetch first known IP address
myIPExample=hostname --all-ip-addresses | awk '{print $1}'
# start server
php -S ${myIPExample}:8080 -t ./public/ ./router.php

You can now access the site from within your network at http://${myIPExample}:8080.

Change the layout, maintain the content

The following folders have been setup with minimal example content and templates:

• content Markdown content with YAML frontmatter
• template Twig templates for your HTML
• public is your document root. CSS should go there.

Exporting functions to twig

In your public/index.php:

use Macrominds\App;
use Macrominds\DefaultConfig;

require_once __DIR__ . '/../vendor/autoload.php';

$app = new App(realpath(__DIR__ . '/..'));

$app->configure(
    (new DefaultConfig())->merge(
        [
            'template-engine' => [
                'exported'   => [
                    'functions' => [
                        'css' => function (string $name): string {
                            return "/css/{$name}";
                        },
                    ],
                ],
            ],
        ]
    )
);

$app->run();

Usage in twig template:

<link href="{{ css("/css/app.css") }}" rel="stylesheet">

Add content

The framework is resource oriented. So if you want to provide /an-url.html, you need to create an-url.yml.md in the content folder.

A minimal .yml.md file consists of so called „Frontmatter“ (yaml) and the content (markdown).

It looks like this:

---
title: my page title
---
# My heading

My paragraph.

You can change the template:

---
template: demo
---
Another template is used here.

You can specify to treat the markdown section as a Twig template, by setting the is_template parameter to true:

---
is_template: true
---
You requested {{ requested_path }}

To be continued…

This very basic documentation will be complemented soon.

Deployment

Server system requirements

You need php 7.3 or php 7.4 and mod_rewrite. Composer, git and ssh access are required for auto deployment.

Provisioning tools

I recommend using Uberspace.

See https://gitlab.com/macrominds/provision/uberspace for ansible roles that are specially tailored for Uberspace and macrominds/website.

You can combine them as follows. Configure ssh access for your Uberspace and run ansible-playbook -i my-website, site.yml to provision it. Most likely, I will provide a detailed example project soon.

site.yml:

---
- hosts: all
  roles:
    - role: lib-webp
    - role: web-domains
      web_domains_list:
        - my-website.com
        - www.my-website.com
    - role: mail-domains
      mail_domains_list:
        - my-website.com

    - role: web-prerequisites
    - role: web-provide-shared-deployer-dot-env
    - role: web-logrotate

    - role: deployment-key
      deployment_key_local_path: ~/.ssh/my-deploy-key

    - role: web-link-html-to-deployer-target

An Uberspace server, provisioned that way, is ready to be used for auto deployment.

Manual deployment

You can delete deploy.php and hosts.yml if you don't plan to use auto deployment. In that case, you can also run composer remove deployer/deployer deployer/recipes.

Don't forget to set your document root after having performed the steps of either „Pure manual deployment“ or „Manual deployment with composer“ for the first time.

Pure manual deployment

For pure manual deployment, run composer install --no-dev --optimize-autoloader locally. Afterwards upload the following files and folders:

• content
• templates
• public
• vendor
• .env But make sure to adapt it to production settings: APP_ENV=production

Manual deployment with composer

You can delete deploy.php and hosts.yml if you don't plan to use auto deployment.

If you have Composer and ssh access, then upload

• content
• templates
• public
• composer.json
• composer.lock
• .env But make sure to adapt it to production settings: APP_ENV=production

On the server, run composer install --no-dev --optimize-autoloader.

Set your document root

Make public your document root. TIP: If you cannot easily modify your document root, try a symlink (e.g. ln -sfn website/public docroot).

Auto deployment

We're using Deployer for auto deployment.

Preparations

Edit hosts.yml to match your git repository and application name.

The keys testing and prod are server names. Either configure your ssh servers (~/.ssh/config) to match the names or rename the keys to your server(s). E.g. replace prod with my-website.com. Of course, you will still need to configure ssh for my-website.com.

If you are using an Uberspace, uncomment the following part of your deploy.php. It is required as a work around for caching problems on the Uberspace.

task('uberspace:reload', function() {
   run('uberspace tools restart php');
});
after('cleanup', 'uberspace:reload');

Run the auto deployment

Run vendor/bin/dep deploy {server-name}, and replace {server-name} by one of your configured servers.

E.g. run vendor/bin/dep deploy prod if you haven't changed the name of it in hosts.yml.

Server configuration

Logrotate

Schedule a cronjob that performs the linux native logrotate.

See macrominds/provision/uberspace/web-logrotate for uberspace provisioning.

Basically, you will want to make a cronjob like this:

@daily /usr/sbin/logrotate -s /home/my-website/.logrotate.status /home/my-website/etc/web-logrotate.conf

And a web-logrotate.conf like this:

weekly

/var/www/virtual/my-website/shared/log/*.log {
    weekly
    missingok
    rotate 8
}

TODO

• Adapt composer.json content (and maybe more templates) to the new project's name
• Complement documentation with details