How to set up Local Beach for Docker-based Neos development on your computer

Overview

"Local Beach" is a development environment which makes it easy to use the Beach Docker images (Nginx, PHP, Redis) as a local development environment for any Neos or Flow project. You don't need a Beach account nor be a Flownative customer in order to use Local Beach. And sure, Local Beach is free (as in free beer, or free coffee).

Note: We'd love to hear your feedback! How did work things out for you? Anything which went wrong? Have a question or an idea for additional features? Just write uns an email to team@flownative.com or use the chat on our website.

System Requirements

You might be able to use Local Beach in other environments, but this guide assumes that you have the following software running:

• A computer running macOS or Linux
• Docker Desktop, OrbStack or any other Docker (and Docker Compose) setup
• Homebrew

Make sure that you are not running any other webserver on port 80 or database on port 3307 (that's a non-standard port).

Installing the Local Beach CLI

Install Beach CLI by running the following commands (using Homebrew):

Hint: Upgrade localbeach frequently, because we are rolling out bugfixes and new features on a regular basis. You can do so by running:

Using Local Beach for Development

Local Beach provides a reverse proxy and a database server (running in Docker) for all of your local projects. These are shared between projects.

Then it runs a set of Docker containers for each project you develop locally. They use the same PHP, Nginx and Redis images which we use for hosting your Beach project in the cloud. Setting up Local Beach for an existing Neos or Flow project consists of the following steps:

• create the project and install the packages using composer (i.e. run composer install)
• initialize a Local Beach setup for your project
• start containers
• import existing content

The first step depends on how you usually work. Create a project from scratch or clone an existing repository, the main point is: It must be a Composer-based Neos or Flow project. Then run composer install before you proceed. If you have no PHP and/or Composer binary on your machine, or the PHP version you have does not match the PHP version you (want to) use with Local Beach, checkout out How to work with Composer in Local Beach.

Initialize Project

In a terminal window, switch to your Neos or Flow project main directory and initialize the Local Beach configuration. Note that the project name must be unique on your local computer and must be DNS compatible: only use characters (a-z), numbers (0-9) and hyphens (-).

If all you get is an error message telling you Could not find Flow or Neos installation in your current path! you did not yet run composer install to set up your project. Do that and try again.

Feel free to edit the generated .localbeach.dist.env file and specify which PHP version you'd like to use or set up additional hostnames for multi-site projects.

The two generated files (.localbeach.dist.env and .localbeach.docker-compose.yaml) can be checked in to version control. Should you need per-machine environment variables, those can be set in a .localbeach.env or .env file for each developer individually.

Start Containers

You can now start the containers by using and follow the log output of the containers to see when they are ready. The PHP container will copy the files of your project into the container. This may take a moment, so don't worry if you get a "Connection closed by remote host" error when you try to connect with SSH. If you follow the log output of the PHP container, you'll see the the message "ready to handle connections" when the container is ready.

Try to access your project through a browser using the Local Beach URL (http://wwwneosio.localbeach.net in the example above). If your project is a Neos site, there likely won't be any content yet to see, you may even see a Neos database error. That's fine – let's just import the content in the next steps.

You can access the Local Beach project in order to run ./flow commands, for example for flushing the cache:

Import Existing Content

• you can access your database using your tool of choice at 127.0.0.1 on port 3307 with user "root" and password "password"
• the Data/Persistent directory of your local machine is mounted automatically with the directory inside your container; so just copy any data into that directory
• you can also import your persistent data from a Beach instance by using beach resource-download --instance <your-instance-id> --namespace <your-namespace>

Working on the Code

Since the root of your project is mounted inside the container (at /application), you can work on the code on your host, using your favourite editor or IDE. No need to sync or set up some copy workflow into the container.

After code changes Flow & Neos will pick them up as expected – unless you changed the default base context from Development to Production.

Stopping your Local Beach instance

If you have a lot of projects running at the same time, your computer might get a bit slow. Just stop the projects you don't need at the moment by using this command:

In case you want to stop all running instances as well as the shared database and nginx container, you can use

More Commands

There are more commands not mentioned in this document. You can explore them by using the built-in help. Make sure to read the help text, so you know what to expect when you run a command!

More Questions

Q: Can I use multiple subdomains per instance?

Yes, you can add additional virtual host names or rename the existing name, for example in order to develop a multi-site Neos project. Simply change the BEACH_VIRTUAL_HOSTS environment variable to a comma-separated list of domain names and add that to your .localbeach.dist.env.

We hope you like Local Beach and it will help you working on Neos and Flow projects with even more joy.

Your Flownative Team