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, use the chat on our website or tweet a tweet @flownative.

System Requirements

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

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):

$ brew tap flownative/flownative
$ brew install localbeach
$ beach version

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

$ brew upgrade localbeach

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 (-).

$ cd ~/MyProjects/www.neos.io/
$ beach init --project-name wwwneosio

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

$ beach start
INFO You are all set
INFO When files have been synced, you can access this instance at http://wwwneosio.localbeach.net

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:

$ beach exec

          Flownative Local Beach

          wwwneosio

beach@714cab3ae9cd:/application$ ./flow
Neos dev ("Development/Beach/Instance" context)
usage: ./flow <command identifier>

See "./flow help" for a list of all available commands.

Import Existing Content

  • you can access your database (for example using Sequel Pro) at 127.0.0.1 on port 3307 with user "root" and password "password"
  • the Data/Persistent directory of your local machine is mirrored 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>

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:

$ beach stop

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

$ beach down

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!

$ beach
beach is the tool for managing projects in Beach and Local Beach.

Usage:
  beach [command]

Available Commands:
  down              Stop instances, reverse proxy and database server and remove containers
  exec              Execute a command in or enter a Local Beach container
  help              Help about any command
  init              initialize a Local Beach instance in the current directory
  logs              Display logs of the Local Beach instance container
  pause             Temporarily stop the reverse proxy and database server
  resource-download Download resources (assets) from a local Flow or Neos installation to Beach
  resource-upload   Upload resources (assets) from a local Flow or Neos installation to Beach
  restart           restart the Local Beach instance in the current directory
  resume            Resume the temporarily paused reverse proxy and database server
  setup             Setup Local Beach on this computer
  setup-https       Setup HTTPS for Local Beach projects
  start             Start the Local Beach instance in the current directory
  status            Display the status of the Local Beach instance containers
  stop              Stop the Local Beach instance in the current directory
  version           Print the version number of Beach

Flags:
  -h, --help   help for beach

Use "beach [command] --help" for more information about a command.

$ beach help logs
This command allows you to either display the content of log files
found in Data/Logs/* (default) or show the console output of the
Docker containers (--containers).

Usage:
  beach logs [flags]

Flags:
  -c, --containers   Show log of container console output
  -f, --follow       Follow log output
  -h, --help         help for logs
  -t, --tail int     Number of lines to show from the end of the logs (default 10)

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