jonnitto / uberspace-deployer
Unofficial deployer recipes for Uberspace interacting with Neos CMS
Fund package maintenance!
jonnitto
www.paypal.me/Jonnitto/20eur
Installs: 691
Dependents: 0
Suggesters: 0
Security: 0
Stars: 11
Watchers: 4
Forks: 4
Open Issues: 3
Type:neos-build
Requires
- php: ^7.3 || ^8.0
- ext-intl: *
- deployer/deployer: ^6.9
README
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 and the needed actions for deploying a project. Some helper tasks are available that 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 at the root of your project.
For a list of all available commands, enter dep
in the command line
Uberspace
Uberspace is a superb hosting provider from Germany. You can find their 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 the following content:
<?php namespace Deployer; require_once 'Build/Uberspace.Deployer/neos.php';
Create a file with the name deploy.yaml
with the following content and edit it following points:
- Replace
domain.tld
with the corresponding domain, withoutwww.
- Replace
__SERVER__
with the corresponding server name. You'll find the info 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 fileSettings.yaml
in theshared/Configuration/
folder.
This file is used to check if Neos is already installed. If the installation 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 your 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 essential 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 in the correct directory. The default directory for all requests is /var/www/virtual/<username>/html
. But you can also host multiple domains in one instance. You can create folders (and symlinks) in the form of /var/www/virtual/<username>/<domain>
. Make sure your domain is set up 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 a 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 unaccessible.
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, take a look at your uberspace dashboard, or copy the addresses after the dep server:domain:add
command.
Set the Flow Context via .htaccess
You must 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
Usage with ddev
If you use ddev for local development, the task dep flow:import
will not work. You have to enable the setting ddev
to true
to make it work. Please run this task not inside the container.
Slack notifications
The parameter slack_webhook
accepts an array with strings beside a simple string.
With this, you can post the notifications 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
Deployment of staging and production to the same hosts
If you want to have a staging and production instance on the same host, you should set up at least two branches, e.g., staging
and production
. It is recommended that you name the stage
and the branch
name the same.
.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
redis_start_db_number
has to be set because you don't want to share the same Redis database for staging and production. In the Default parameter section, you can read more about this.
Deployment of staging and production to the multiple hosts
.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
Automatic deployment with GitHub actions
In the example folder, you'll find a file called deployment_werkflow.yaml
. To enable automatic deployments via GitHub actions, you have to put a file like this in your repository under .github/workflows/deploy.yaml
This example is just meant as an inspiration; you can (and should) edit this to fit your needs. In this workflows are some GitHub secrets you can set:
Default parameter
This package sets some default parameters. All of them are defined in config.php.
You can override them in your yaml
or directly in your PHP
file.
Neos & Flow related
flow_context
(string)
Set the context from flow. Defaults to Production/Live
shared_dirs
(array)
These folders get shared over all deployments. Defaults to
shared_dirs: - Data/Persistent - Data/Logs - Configuration
upload_assets_folder
(array)
These folders (globbing-enabled) will get uploaded from the current installation.
Primarily used for rendered CSS & JS files, which you don't want in your repository.
To disable the upload you can set this to false: set('upload_assets_folder', false);
or in the yaml
file: upload_assets_folder: false
.
Defaults to
upload_assets_folder: - DistributionPackages/*/Resources/Private/Templates/InlineAssets - DistributionPackages/*/Resources/Public/Scripts - DistributionPackages/*/Resources/Public/Styles
db_name
& database
(string)
If Neos is already installed, it will use the flow command configuration:show
to get the database name. Otherwise, it will check if the value database
is set and use this as a prefix for the required username from Uberspace. If nothing specific is set it will convert the repository name to camel case, append _neos
, and also (if specified) the name of the stage
.
redis_start_db_number
(integer)
Defaults to 2
redis_defaultLifetime
(integer)
Defaults to 0
redis_databases
(array)
Defaults to
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 (array)
This sets the database names (based on redis_databases
) with the corresponding number (based on redis_start_db_number
)
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
Server related
editor
(string)
Defaults to nano
html_path
(string)
Defaults to /var/www/virtual/{{user}}
deploy_path
(string)
Defaults to {{html_path}}/{{deploy_folder}}
db_backup_folder
(string)
Defaults to {{deploy_path}}/.dep/databases/dumps
db_backup_keep_dumps
(integer)
Defaults to 5
deploy_folder
(string)
Defaults to the repository name. If a stage
is set, the stage will be placed in a subfolder of this folder. Example: Your repository has the name owner/MyNeosProject with the stage production
. In that case, the deploy_folder
will be MyNeosProject/Production
.
release_name
(string)
This is set to the current date and time. Example: 2021-01-30__13-40-10
Git related
git_commit_types
(array)
You can set the types of commits for the command git:commit
.
Per default, it is based on commitizen.
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)'