Overview

"Local Beach" is a development environment which makes it easy to use the Beach Docker images (Nginx, PHP, Redis and Elasticsearch) 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: Local Beach is currently in an early beta phase. Conventions may change, things will become easier, and some aspects may be not as stable yet as we want them to be. If that does not scare you off, you are welcome to try out Local Beach and help us improving it by giving us feedback.

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

    • Docker for Mac
    • Homebrew
    • PHP 7.1 or higher for the command line (for example, PHP provided by Apple as part of macOS)

    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 Beach CLI

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

    brew tap flownative/flownative
    brew install beach-cli
    beach --version
    Hint: Upgrade beach-cli frequently, because we are rolling out bugfixes and new features on a regular basis. You can do so by running:
    brew upgrade beach-cli
    Note: In case you do not have Homebrew, you can install Beach CLI by following the Linux instructions. It's just a little less convenient.
  • System Requirements

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

    • Linux or something similar
    • Docker 17.12.0 (or later) and Docker Composer 1.18.0 (or later)
    • PHP 7.1 or higher for the command line

    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 Beach CLI

    Install Beach CLI by running the following commands:

    curl -LO https://storage.googleapis.com/cli-tool.beach.flownative.cloud/beach.phar
    mv beach.phar /usr/local/bin/beach
    chmod +x /usr/local/bin/beach
    beach --version
    Hint: Upgrade beach-cli frequently, because we are rolling out bugfixes and new features on a regular basis. You can do so by simply re-running the installation commands given above.

    Preparing Local Beach

    To be able to run projects in Local Beach, you need to prepare some infrastructure once. To do this, run:

    beach localbeach:prepare "~/.Flownative/Local Beach/Docker" "~/.Flownative/Local Beach/MariaDB"

Setup Local Beach for a Project

Local Beach is an application (running in Docker) providing a reverse proxy and a database server for all of your local projects.

Before your continue you need to make sure that you have an SSH key generated and added to your SSH Agent. Here's a guide about that, if you need any help.

You need to initialize Local Beach once using the following command:

✗ beach localbeach:setup

Start Local Beach

This step needs to be done after restarts of Docker (including restarts of the computer). It just starts the Local Beach database and http server:

✗ beach localbeach:start

Using Local Beach for Development

Local Beach 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:

  • initialize a Local Beach setup for your project
  • start containers
  • import existing content

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 local:init --projectName wwwneosio --createDatabase

If you already have other Local Beach projects running on your computer, you need to adjust the SSH port for the new project. Simply edit the generate .localbeach.dist.env file and set a different port. In that file you can also specify which PHP branch you'd like to use or set up additional virtual hosts for multi-site projects.

Hint: If you chose the wrong project name or simply would like to re-generate the Local Beach files for your project, you can do so using the --force option.

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 local:start
Pulling webserver ... done
Pulling php       ... done
Pulling redis     ... done
Creating wwwneosio-webkatalog_php       ... done
Creating wwwneosio-webkatalog_webserver ... done
Creating wwwneosio-webkatalog_redis     ... done


 [OK] You are all set


 When files have been synced, you can access this instance at:
 http://wwwneosio.localbeach.net

✗ beach local:logs -f

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 via SSH in order to run ./flow commands, for example for flushing the cache. By default you can reach the project via port 2222 using the user beach. If you are running multiple Local Beach projects (and you will …), you need to set a different port number for each project in the .localbeach.dist.env file of your project.

Hint: You can use beach local:ssh for logging into your instance, so you don't need to lookup the respective port number

✗ beach local:ssh
…
beach@714cab3ae9cd:/application$ ./flow
Neos 4.0.3 ("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 -i instance-<your-instance-id>

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 local:stop

More Commands

In the meantime there may be new commands we implemented which are not mentioned in this document. You can explore them by using the list and help commands. Make sure to read the help text, so you know what to expect when you run a command!

$ beach list
Beach CLI 0.6.0

Usage:
  command [options] [arguments]

Options:
  -h, --help            Display this help message
  -q, --quiet           Do not output any message
  -V, --version         Display this application version
      --ansi            Force ANSI output
      --no-ansi         Disable ANSI output
  -n, --no-interaction  Do not ask any interactive question
  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Available commands:
  help                Displays help for a command
  list                Lists commands
 local
  local:database:sql  Sent SQL commands to this projects database.
  local:down          Stop the Local Beach instance in this directory and remove its containers and volume.
  local:init          Initialize a Flow distribution as a Local Beach project
  local:logs          Fetch the logs of the Local Beach instance container.
  local:ssh           Login in to a Local Beach instance via SSH.
  local:start         [local:up] Start the Local Beach instance in this directory.
  local:status        Show status of the Local Beach instance container.
  local:stop          Stop the Local Beach instance in this directory.
 localbeach
  localbeach:setup    
  localbeach:start    
  localbeach:stop     
  localbeach:upgrade  
 resource
  resource:download   Download resources (assets) from Beach to a local Flow or Neos installation

$ beach help local:logs
Usage:
  local:logs [options]

Options:
  -f, --follow          Follow log output
  -h, --help            Display this help message
  -q, --quiet           Do not output any message
  -V, --version         Display this application version
      --ansi            Force ANSI output
      --no-ansi         Disable ANSI output
  -n, --no-interaction  Do not ask any interactive question
  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Help:
  Fetch the logs of the Local Beach instance container.

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