Docker

If you don't already have a local environment or you're not familiar with Docker, this page will guide you in installing UserFrosting using Docker.

Docker provides a great starting point for building a UserFrosting application using PHP, NGINX, and MySQL without requiring prior Docker experience. All the necessary tools will be available through Docker. The only necessary tool required on your computer, besides Docker, is the command line.

If you're familiar with PHP development, or already have PHP installed locally, you may instead want to consider setting up natively.

Command Line Interface

The command line interface will be required to perform most tasks in this guide. It's usage depends on your OS :

MacOS

If you're using MacOS, the Terminal is already installed on your computer. You'll find the app in /System/Applications/Utilities/Terminal.

Linux

Every Linux distro uses the command line. On Ubuntu for example, you can find a launcher for the terminal by clicking on the Activities item at the top left of the screen, then typing the first few letters of "terminal", "command", "prompt" or "shell".

Windows

The easiest way to setup a local dev environnement on Windows is through Windows Subsystem for Linux (WSL2). This is basically running Linux inside Windows. Best of both worlds! This also means most installation instructions for Windows you'll find on the internet won't work, as we're not technically on Windows, we're on Ubuntu. We'll instead use the Ubuntu installation instructions!

See this guide for more detail on this process : Set up a WSL development environment. The gist of it is :

1. Open Windows Terminal, which can be found in the Microsoft Store.
2. Open the terminal and install WSL2 distro : wsl --install.
3. During installation, enter a unix user with a password. Remember this password, you'll need it later!
4. Restart Windows Terminal and open a new Ubuntu terminal. Each subsequent CLI usage on Windows will be from this Ubuntu terminal.

When using Windows and WSL2, keep in mind your project files will be stored inside the Linux file system. For example, your project files will be in the Linux file system root directory (\\wsl$\<DistroName>\home\<UserName>\Project), not the Windows file system root directory (C:\Users\<UserName>\Project or /mnt/c/Users/<UserName>/Project$). See Microsoft guide on file storage for more information.

Install Docker

First, you'll need to install Docker. Just follow the installation instructions from the Docker website:

• Mac
• Windows (via WSL2)
• Linux

Get UserFrosting

For the next part, you'll need to use the command line. We'll use Composer (through a Docker image) to create an empty project, with the latest version of the UserFrosting skeleton, into a new UserFrosting subdirectory:

docker run --rm -it -v "$(pwd):/app" composer create-project userfrosting/userfrosting UserFrosting "^5.1" --no-scripts --no-install --ignore-platform-reqs

Build Containers & Setup UserFrosting

Now it's simply a matter of navigating to the directory containing the source code you just downloaded, building the containers, starting them, then installing UserFrosting.

1. Navigate to the directory:

   cd UserFrosting

   If you customized UserFrosting in the previous command, don't forget to change it in the command above.

2. Build each of the Docker Containers (this might take a while):

   docker-compose build --no-cache

3. Start each Docker Container:

   docker-compose up -d

4. Set some directory permissions (your may have to enter your root password):

   sudo touch app/logs/userfrosting.log
   sudo chown -R $USER: .
   sudo chmod 777 app/{logs,cache,sessions}

5. Install PHP dependencies:

   docker-compose exec app composer update

6. Install UserFrosting (database configuration and migrations, creation of admin user, etc.). You'll need to provide info to create the admin user:

   docker-compose exec app php bakery bake

Now visit http://localhost:8080 to see your UserFrosting homepage!

You should see the default UserFrosting pages and be able to login with the newly created master account.

To stop the containers, run :

docker-compose stop

Mailpit

You can see captured email at http://localhost:8025.

UserFrosting's default docker-compose.yml file contains a service entry for Mailpit. Mailpit intercepts emails sent by your application during local development and provides a convenient web interface so that you can preview your email messages in your browser.

While UserFrosting is running, you may access the Mailpit web interface at: http://localhost:8025.

Working with UserFrosting

Every Bakery command needs to be wrapped in Docker Compose syntax, since you need to run these commands in the containers, not your computer.

For example:

docker-compose exec app php bakery ...

Working with the Containers

If you need to stop the UserFrosting docker containers, just change to your userfrosting directory and run:

docker-compose stop

To start containers again, change to your userfrosting directory and run:

docker-compose up -d

If you need to purge your docker containers (this will not delete any source file or sprinkle, but will empty the database), run:

docker-compose down --remove-orphans

And then start the installation process again.

Advanced configuration

At the heart of everything is the docker-compose.yml file. If you're experienced with Docker and Docker Compose, this is where you can customize your Docker experience. For example, you can customize the port each service runs on. And since the file is located in your Sprinkle, aka your app, it's possible to save this file in your repo.

The docker-compose.yml file also contains the MySQL database and Mail environment variables. Since these variables are defined globally inside the container, they don't need to be redefined inside the .env file.

Production environment

This is not (yet) meant for production!

You may be tempted to run with this in production, but this setup has not been security-hardened. For example:

• The database is exposed on port 8593 so you can access MySQL using your favorite client at localhost:8593. However, the way Docker exposes ports bypasses common firewalls like ufw. This should not be exposed in production.
• Database credentials are hard-coded — obviously not secure.
• File permissions may be more open than necessary.
• HTTPS is not implemented.
• It just hasn't been thoroughly tested in the capacity of being a production system.

If you're experienced with Docker in a production environment, don't hesitate to reach out and contribute to this documentation.