"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 email@example.com, use the chat on our website or tweet a tweet @flownative.
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 or plain ol' Docker (and Compose) for Linux
Make sure that you are not running any other webserver on port 80 or database on port 3307 (that's a non-standard port).
$ 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.
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.
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
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)
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