Deployer tasks for Uberspace & Neos CMS

These deployer scripts are built on top of Deployer. Most of the tasks are provided by this library already; this package adds just some optimization for the install process as well as the needed actions for deploying a project. There are also some helper tasks available, who should make your life as a developer a bit easier. Please run the deployer scripts only in your development environment, as Deployer connects automatically to the needed server.

You can look at the example folder to look how to set up a deployment. The files should be saved on the root of you project.

For a list of all available commands enter dep in the command line

Uberspace

Uberspace is an awesome hosting provider from Germany. You can find theirs complete manual here.

First, you have to register your own uberspace. Then, add your SSh key to the admin-interface. If you don't know what SSH is, you can read more about this in the SSH section in the uberspace manual or on the SSH manual on github.

Installation of the deployment scripts

Enter this on the root of your project:

composer require --dev jonnitto/uberspace-deployer

Create a file with the name deploy.php with following content:

<?php

namespace Deployer;

require_once 'Build/Uberspace.Deployer/neos.php';

Create a file with the name deploy.yaml with following content and edit it following points:

• Replace domain.tld with the corresponding domain, without www.
• Replace __SERVER__ with corresponding server name. You'll find the infos on the uberspace dashboard.
• Replace __USER__ with the corresponding uberspace username
• Replace __OWNER__/__REPOSITORY with the corresponding repository
• Add the slack_webhook. (optional) You can register it here

# To start a deployment or the
# installation run `dep deploy`

domain.tld:
  hostname: __SERVER__.uberspace.de
  user: __USER__
  repository: git@github.com:__OWNER__/__REPOSITORY__.git
  slack_webhook: https://hooks.slack.com/services/__YOUR/SLACK/WEBHOOK__

The command dep deploy checks if Neos is installed and starts either the installation process or a fresh deployment.

Warning
Do not delete the file Settings.yaml in the shared/Configuration/ folder.
This file is used to check if Neos is already installed. If the installtion fails, please remove the whole folder and start again.

The --composer_auth input option for the tasks

If you want to pass an authentication configuration (for private repositories) during deploy task, you can do this via the --composer_auth input option:

Example:

dep install --composer_auth "http-basic.repo.packagist.com token XYZ"

This option doesn't add the authentication global to composer on the host, just locally. If you want to install the authentication globally, connect via dep ssh to the server and enter (as an example) composer config --global --auth http-basic.repo.packagist.com token XYZ in the CLI.

Add a domain

The add a domain to you uberspace, you can either follow the instructions on the uberspace manual
or run the command dep server:domain:add.

Cronjobs

To edit the cronjobs on the server run the command dep server:cronjob.
In the case you have to run a CLI PHP command, it is important to set the full path to the PHP binary.

Publish the document root

In order for a website to be accessible to visitors, it must be published to the correct directory. The default directory for all requests is /var/www/virtual/<username>/html. But you can also host multiple domains on one instance. You can create folders (and symlinks) in the form of /var/www/virtual/<username>/<domain>. Make sure your domain is setup and configured correctly. To use RewriteRules, you have to create a .htaccess file within the DocumentRoot with the following content: RewriteBase /. In the example folder you'll find an example of an .htaccess file with dynamic FLOW_CONTEXT configuration based on the URL.

Warning
Do not delete the /html folder. If this folder doesn’t exist, the RewriteRules
implementing the additional DocumentRoots don’t work, so all your domains will be unaccessable.

You can use the command dep server:symlink:add to create a correct symlink

Set the DNS records

To go live the A (IPv4) and the AAAA (IPv6) Records need to be set in the domain DNS settings. To find out which are the correct IP addresses you take a look at your uberspace dashboard, or copy the addresses after the dep server:domain:add command.

Set the Flow Context via .htaccess

It is very important that you have set the FLOW_CONTEXT correctly.

Example:

# Dynamic context configuration:
SetEnvIf Host \.test$ FLOW_CONTEXT=Development
SetEnvIf Host \.prod$ FLOW_CONTEXT=Production/Local
# SetEnvIf Host \.space$ FLOW_CONTEXT=Development/Live

<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteCond %{HTTP_HOST} !\.test$
    RewriteCond %{HTTP_HOST} !\.prod$
    # RewriteCond %{HTTP_HOST} !\.space$
    RewriteRule (.*) $1 [E=FLOW_CONTEXT:Production/Live]
</IfModule>

General commands

Run these tasks with dep COMMAND. If you want to list all commands, enter dep or dep list

Slack notifications

The parameter slack_webhook accepts beside an simple string also an array with strings.
With this you are able to post the notifictions to multiple channels.

Example:

domain.tld:
  slack_webhook:
    - https://hooks.slack.com/services/__SLACK/WEBHOOK/CHANNEL_ONE__
    - https://hooks.slack.com/services/__SLACK/WEBHOOK/CHANNEL_TWO__
    - https://hooks.slack.com/services/__SLACK/WEBHOOK/CHANNEL_N__

Deployment to multiple stages and/or via GitHub Actions

.base: &base
  hostname: __SERVER__.uberspace.de
  user: __USER__
  repository: git@github.com:__OWNER__/__REPOSITORY__.git

domain.tld:
  <<: *base
  branch: production
  stage: production

staging.domain.tld:
  <<: *base
  branch: staging
  stage: staging
  redis_start_db_number: 10

.base: &base
  repository: git@github.com:__OWNER__/__REPOSITORY__.git

domain.tld:
  <<: *base
  hostname: __SERVER_PROD__.uberspace.de
  user: __USER_PROD__
  branch: production
  stage: production

staging.domain.tld:
  <<: *base
  hostname: __SERVER_STAGE__.uberspace.de
  user: __USER_STAGE__
  branch: staging
  stage: staging

Default parameter

This package set some default parameter. All of them are defined in config.php.
You can override them in your yaml or directly in your PHP file.

shared_dirs:
  - Data/Persistent
  - Data/Logs
  - Configuration

upload_assets_folder:
  - DistributionPackages/*/Resources/Private/Templates/InlineAssets
  - DistributionPackages/*/Resources/Public/Scripts
  - DistributionPackages/*/Resources/Public/Styles

redis_databases:
  - Flow_Mvc_Routing_Route
  - Flow_Mvc_Routing_Resolve
  - Neos_Fusion_Content
  - Flow_Session_MetaData
  - Flow_Session_Storage
  - Neos_Media_ImageSize
  - Flow_Security_Cryptography_HashService

redis_databases_with_numbers:
  Flow_Mvc_Routing_Route: 2
  Flow_Mvc_Routing_Resolve: 3
  Neos_Fusion_Content: 4
  Flow_Session_MetaData: 5
  Flow_Session_Storage: 6
  Neos_Media_ImageSize: 7
  Flow_Security_Cryptography_HashService: 8

git_commit_types:
  Fix: A bug fix
  Update: A backwards-compatible enhancement
  Breaking: A backwards-incompatible enhancement
  Docs: Documentation change
  Build: Build process update
  New: A new feature implementation
  Upgrade: Dependency upgrade
  Chore: 'Other changes (e.g.: refactoring)'