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 dump 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


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. You can pick any name which makes it easy for you to recognize the project again. For many projects, the main domain name is a good pick.

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.

Beach supports projects with Flow 3.3.x and higher as well as Neos 2.3.x and higher.

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 database dump

Using the connection info from your instance view try to log in to your new instance via SSH. If the connection times out, your instance might not be ready yet – just wait a little more and try again.

When you successfully logged in, you can log out again and proceed with importing the database content of your website.

In order to access the database server of your instance from your computer you need to create an SSH tunnel.

Open a terminal window and run the following command after replacing the database server identifier and instance identifier with your actual instance identifiers:

ssh -J beach@ssh.flownative.cloud -nNT -L 3307:database-8f594285-bce3-4456-af2d-72cf83d56629:3306 beach@instance-156c4db-0125-457d-b6ce-218f6f9d1596

You can now try to connect to the remote database from your computer by running the following in a separate terminal window:

mysql --host=127.0.0.1 --port=3307 --user=pvy3sc2dirdxb9mk --password=1luZ58khlodKMQjTF8Q5AfAcNl6Q7zP --database=m2fmzatzm0rymc4v

Note that "localhost" would try to connect you to your local MySQL socket (if any) and ignore any port you specify. That's why it is important to specify "127.0.0.1" as the database host.

If you succeeded with connecting to your database, leave the interactive session by entering "quit" and pressing enter. Now you can import the SQL dump by running something like the following:

mysql --host=127.0.0.1 --port=3307 --user=pvy3sc2dirdxb9mk --password=1luZ58khlodKMQjTF8Q5AfAcNl6Q7zP --database=m2fmzatzm0rymc4v < my_neos_website.sql

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 files 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 the Google Cloud Storage plugin

If you have lots of assets or are migrating a website which is already in production, you need a different way to import your resources.

In general, you need to install the Google Cloud Storage Flow package at your current website, set some configuration and then use a ./flow command to copy all the resources to the cloud storage.

First, install the Flownative Google Cloud Storage package:

composer require flownative/google-cloudstorage:4.*

If you are using Neos 2.3.* you need the a different version of the plugin:

composer require flownative/google-cloudstorage:3.*

Next, you need to get the private key and further configuration for accesing your Google Cloud Storage buckets (please be careful with this data and delete it after you are done with the migration):

Log in to your instance via SSH:

ssh -J beach@ssh.flownative.cloud beach@instance-156c4db-0125-457d-b6ce-218f6f9d1596

Show the relevant environment variables:

env | grep BEACH_GOOGLE_CLOUD_STORAGE

In the global Configuration directory of your Flow or Neos project, create a new Settings.yaml or edit an existing one. It's important that the settings you are going to add will override the default settings of the Google Cloud Storage package - that's why you make them global.

Now add the following:

Neos:
  Flow:
    resource:
      storages:
        beachPersistentResourcesStorage:
          storage: 'Flownative\Google\CloudStorage\GcsStorage'
          storageOptions:
            bucket: '-- BEACH_GOOGLE_CLOUD_STORAGE_STORAGE_BUCKET --'
            keyPrefix: '/'
      collections:
        beach:
          storage: 'beachPersistentResourcesStorage'
          target: 'localWebDirectoryPersistentResourcesTarget'

Flownative:
  Google:
    CloudStorage:
      profiles:
        default:
          credentials:
            clientEmail: '-- BEACH_GOOGLE_CLOUD_STORAGE_SERVICE_ACCOUNT_IDENTIFIER --'
            privateKeyJsonBase64Encoded: '-- BEACH_GOOGLE_CLOUD_STORAGE_SERVICE_ACCOUNT_PRIVATE_KEY --' 

Note: if you are using Neos 2.3, make sure to use "TYPO3:" instead of "Flow:". And pay attention that the YAML file is still valid configuration, for example make sure that you don't have two "Neos:" sections in the same file.

Now manually replace the variables ("-- BEACH... --") by their actual values. The result then looks something like this:

Neos:
  Flow:
    resource:
      storages:
        beachPersistentResourcesStorage:
          storage: 'Flownative\Google\CloudStorage\GcsStorage'
          storageOptions:
            bucket: 'storage.instance-169cc55d-d16e-4941-b9aa-b72dcff39fd7.euw1.beach.flownative.cloud'
            keyPrefix: '/'
      collections:
        beach:
          storage: 'beachPersistentResourcesStorage'
          target: 'localWebDirectoryPersistentResourcesTarget'

Flownative:
  Google:
    CloudStorage:
      profiles:
        default:
          credentials:
            clientEmail: 'b-pvw4w7otga872o3797oy50o5fpjc@flownative-beach.iam.gserviceaccount.com'
            privateKeyJsonBase64Encoded: 'ewogICJ0eXBlIj…dC5jb20iCn0K'

You can now try to connect to your storage by using this command:

./flow gcs:connect storage.instance-169cc55d-d16e-4941-b9aa-b72dcff39fd7.euw1.beach.flownative.cloud

If that worked out, you are ready to copy all your existing resources into the new storage bucket:

./flow resource:copy persistent beach

All your resources should now exist in your cloud storage.

Final steps

Uploaded all the content and assets? Then it's time to publish resources and see if everything is working.

Publish resources

Log in to your instance via SSH using the "ssh -J ..." command shown in your connection info tab. Once you're in your instance shell, publish all the resources:

./flow resource:publish

If that worked out without any unexpected errors, head over to your instance's public URL and see if your website comes up.

Final words

That sounded like an awful lot of steps and rocket science? We got you. Of course we don't want you to get lost in tunnels and spend your day copy & pasting commands into a shell. That's why we're working on a nice Beach command line tool which will do all the heavy-lifting for you.

And if something didn't work out like you expected, we're all ears: just get in touch with us via our chat or send us an email.