Guides related to Beach
How to migrate a Neos site to Beach
This tutorial takes you through the steps for creating a project and instance on Beach and importing existing content of a Neos website.
Overview
This tutorial takes you through the steps for creating a project and instance on Beach and importing existing content of a Neos website.
You will need the following before starting with this tutorial:
- a Git repository containing a Neos distribution
- a working Composer setup (that is, you need to use Composer for package management and have composer.lock as part of your Git repo)
- a MySQL or MariaDB database export containing all tables of your Neos website
- assets (Flow resources) of your website stored in a local directory (usually in Data/Persistent/Resources)
- a computer which has SSH and the MySQL / MariaDB client installed
Prepare your project
Install flownative/google-cloudstorage
This step is mandatory if you want to be able to do anything with persistent resources (i.e. upload images or other assets). It's easy, though:
composer require flownative/google-cloudstorage
Now commit and push the changed composer.lock file and you are set. Unless configured, the package does not interfere with anything, so there is nothing to worry about. The needed configuration for Beach is explained later in this guide.
Create a project and instance
Log in to the Beach Control panel at https://beach.flownative.com and go to the "Projects" view of your organization. Click on "Create Project".
Next you need to specify a name for your project. Pick any name which makes it easy for you to recognize the project again. For many projects, the main domain name is a good choice.
Then enter the full URL of the Git repository containing your Neos or Flow distribution. The distribution must contain a composer.json and composer.lock file.
If your Git repository is non-public, you need to set the given SSH public key as a deployment key for your repository. Please also make sure that all other packages mentioned in your composer.json / composer.lock are either public or accessible with the given SSH key. Beach only needs read access to your repository.
When you created the project, go to the "Instances" tab and click the "New Instance" button. In the following dialog you need to specify the name of your new instance (something like "Production", "Staging Relaunch", ...), a fitting instance type and pick a branch of your Git repository which should be used.
After creating the instance you will end up a screen displaying details and actions for your new instance. Beach will automatically check for the latest commit and start building a Docker image for the latest code.
When the build is done, the "Deploy" button becomes active. Deploy your new instance for the first time.
The actual container deployment will be finished after a couple of seconds, but the instance needs some additional time to be started create the initial database structure (on each deployment "./flow doctrine:migrate" is called). It may take 1-2 minutes for the instance to be ready.
Import the website assets
Your Beach instance is using Google Cloud Storage for storing and providing the persistent resources of the Neos site or Flow application. All the files in the Docker container of your Beach instance are temporary (ephemeral), there is no persistent file system attached to it. Even though that needs a little rethinking, that is actually a good thing: you can scale your instances up and down and start and stop them without having to think about how to attach a hard drive or shared file system.
Import assets using site import
The easiest way to import your assets is if they exist in your Neos site package (for example, if you are using the Neos Demo site or are currently working on a new website project). In that case, simply ssh into your instance and run a site import:
./flow site:import --package-key YourCompany.YourPackage
Import assets using Local Beach
If you have lots of assets or are migrating a website which is already in production, we recommend using Local Beach. Local Beach is a lightweight client application available for MacOS and Linux and can be installed in seconds.
The installation of Local Beach is explained in this guide.
Open a terminal and switch to the directory containing your Neos project (the one containing the composer.json of your Neos distribution). If you haven't used Local Beach with this project yet, run the following command to initialize it:
beach init
Moving caches to a persistent location
The filesystem of your Beach instances is not persistent and will be replaced with a fresh one on every deploy, this is obviously not great for caching and some caches should be put into a more permanent place.
We will use the database in our snippet below, if you have Redis available for your project you can also use that. We would not suggest using the database for the Neos_Fusion_Content cache for performance reasons.
Flow_Security_Cryptography_HashService: &pdoBackend
backend: 'Neos\Cache\Backend\PdoBackend'
backendOptions:
dataSourceName: 'mysql:host=%env:BEACH_DATABASE_HOST%;dbname=%env:BEACH_DATABASE_NAME%'
username: '%env:BEACH_DATABASE_USERNAME%'
password: '%env:BEACH_DATABASE_PASSWORD%'
defaultLifetime: 0
Flow_Session_Storage: *pdoBackend
Flow_Session_MetaData: *pdoBackend
Further improvements
Install VIPS support
This can speed up image manipulation. If you like to do this, head over to our guide on using VIPS with Neos.
Use Redis for caching
Redis is a very fast key/value store that can provide speed improvements with caching, especially for caches where tagging is used heavily. Configure it following our guide on using Redis with Neos and Flow.