If you don't already have a local environment or you're 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, beside 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.
The command line interface will be required to perform most tasks in this guide. It's usage depends on your OS :
If you're using MacOS, the Terminal is already installed on your computer. You'll find the app in /System/Applications/Utilities/Terminal
.
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".
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 :
wsl --install
.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.
First, you'll need to install Docker. Just follow the installation instructions from the Docker Website:
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/
folder:
docker run --rm -it -v "$(pwd):/app" composer create-project userfrosting/userfrosting UserFrosting "^5.1" --no-scripts --no-install --ignore-platform-reqs
UserFrosting
in the command. This means Composer will create a new UserFrosting/
subdirectory inside the current location. You may change UserFrosting
to anything you like.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.
Navigate to the directory
cd UserFrosting
UserFrosting
in the previous command, don't forget to change it in the command above.Build each of the Docker Containers (this might take a while):
docker-compose build --no-cache
Start each Docker Container:
docker-compose up -d
Set some directory permissions (your may have to enter your root password):
sudo chown -R $USER: .
sudo chmod 777 app/{logs,cache,sessions}
Install PHP dependencies:
docker-compose exec app composer update
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
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.
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 ...
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.
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 contain the MySQL database and Mail environment variables. Since these variables are defined globally inside the container, they don't need to be redefined inside .env
file.
If you wish to run multiple instances of UserFrosting on the same computer with Docker, you must edit the docker-compose.yml
of all but one instance and change the default ports and database volumes / database names.
docker-compose.yml
is already used on your system. For example, if Mailpit is installed locally and running on the default port, you'll get a "address already in use" error when running Docker. This can be solved by changing the port in docker-compose.yml
.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:
ufw
. This should not be exposed in production.If you're experienced with Docker in a production environment, don't hesitate to reach out and contribute to this documentation.