If you already have a local environment and you're familiar with tools like composer, this page will guide you in installing UserFrosting on your existing local environment. If you're don't already have a local environment set up, or you don't want to install the required software natively, you may instead want to consider setting up Homestead as a pre-configured virtual environment.
If your local development environment doesn't already have the required stack and tools, please set these up. You'll need the following:
Make certain that you have properly configured your web server (for example, Apache needs
mod_rewrite enabled), PHP, and the file system permissions.
Please make sure that you have the following installed before attempting to install UserFrosting:
Use git to clone the userfrosting repo into a new folder. In your development directory:
$ git clone https://github.com/userfrosting/UserFrosting.git UserFrosting
UserFrostingat the end of the command. This means
gitwill create new
UserFrostingsubdirectory inside the current location. You can change
UserFrostingto whatever you like.
UserFrosting needs to be able to write to the following directories:
Set your system permissions so that the group under which your webserver runs has read and write permissions for these directories. See File System Permissions for help with this.
Next, we will run Composer to fetch and install the PHP packages used by UserFrosting. Before you do this though, you should check which version of PHP will be run in the command line.
It is very common for a single environment to have multiple different versions of PHP installed. If you've never run PHP from the command line before, you may not realize that the version of PHP run by the webserver (Apache, nginx, etc) can be different from the one that would get run in the command line.
To check the "command line" version, use the command:
$ php -v
You should then see a message like:
PHP 8.0.3 (cli) (built: Apr 12 2021 09:04:34) ( NTS ) Copyright (c) The PHP Group Zend Engine v4.0.3, Copyright (c) Zend Technologies
This is the version of PHP which will be used by Composer. Make sure it meets the minimum required version for UserFrosting!
If it's a lower version than the version that you know your webserver uses, then chances are that your terminal is incorrectly resolving the
php command. This happens because there is an older version of PHP (often preinstalled with your operating system) in one of the paths specified in your path variable (
$PATH in *nix systems,
PATH environment variable in Windows).
If you're using a distribution like XAMPP or WAMP, you'll want to update your
PATH variable so that your terminal finds the same version of PHP that your webserver uses. This process depends heavily on the distribution you're using and your operating system (Google it!) However, the general steps are:
*nixsystems, this can be set in your shell config file, for example
~/.bash_profile. The command should look something like
export PATH="/path/to/newer/version/of/php:$PATH". See this answer on Superuser for information on modifying
PATHin your operating system.
which phpto ensure that the
phpcommand is now resolving to the correct directory. If not, double-check steps 1-3.
PATHvariable in *nix environments, simply run
Once you've got the right version of PHP running from your command line, it's time to run Composer from the directory where you cloned the UserFrosting repo:
$ composer install
This may take some time to complete. If Composer has completed successfully, you should see that a
vendor/ directory has been created under
vendor/ directory contains all of UserFrosting's PHP dependencies - there should be nearly 30 subdirectories in here!
If you only see
wikimedia subdirectories after running
composer install, then you may need to delete the
composer.lock file and run
composer install again.
Before installing, you'll need to create a database and database user account. Consult your database documentation for more details. If you use phpmyadmin or a similar tool, you can create your database and database user through their interface. Otherwise, you can do it via the command line.
You're almost done! We now have the base code and the php dependencies. The remaining steps are to set up the database credentials, create the first user and install the third-party assets. Luckily, at this point, Bakery is here to help! Again, in the main project directory where you cloned UserFrosting, run:
$ php bakery bake
You will first be prompted for your database credentials. This is the information PHP needs to connect to your database. If PHP can't connect to your database using these credentials, make sure you have entered the right information and re-run the
Bakery will also prompt you for SMTP credentials, so that UserFrosting can send emails for activating new accounts and setting and resetting passwords. If you are not ready to set up email at this time, you can choose No email support to skip through SMTP configuration. Please note that in production, you will need to have a working SMTP service. If you do not already have a mail provider, please see our section on mail providers for our recommendations including both free and paid third-party mail services.
If the database connection is successful, the installer will then check that the basic dependencies are met. If so, the installer will run the migrations to populate your database with new tables. During this process, you will be prompted for some information to set up the master account (first user). Finally, the installer will run the
At this point, you should be able to access the basic pages for your application and login with the newly created master account. Visit:
You should see a basic page:
At this point, you should also change your remotes. Since you are starting your own project at this point, rather than working on changes that would eventually be merged into the main UserFrosting repository on GitHub, we'll give the GitHub remote a different, more meaningful name. First, use
git remote -v to see the current remotes:
$ git remote -v origin https://github.com/userfrosting/UserFrosting.git (fetch) origin https://github.com/userfrosting/UserFrosting.git (push)
This basically means that
origin is a shortcut for pushing and pulling to the official UserFrosting repository on GitHub. Let's change that:
$ git remote rename origin upstream $ git remote -v upstream https://github.com/userfrosting/UserFrosting.git (fetch) upstream https://github.com/userfrosting/UserFrosting.git (push)
This renames the
origin remote to
upstream. Let's also disable the
push part of this remote (don't worry, you won't have push rights for the official repo anyway, but this will help us stay organized):
$ git remote set-url --push upstream no-pushing $ git remote -v upstream https://github.com/userfrosting/UserFrosting.git (fetch) upstream no-pushing (push)
Now, if we were to try and push to
upstream for some reason, we'll get a useful error instead of being prompted for credentials.
For future reference (you don't have to do this right now) with the
upstream remote set up, you will be able to pull any updates from the official UserFrosting repository into your project:
$ git fetch upstream $ git checkout master $ git merge upstream/master
See GitHub's article on syncing a fork for more information.
If you are developing as part of a team, you may wish to set up a new
origin remote, for example one that points to a private repo on Bitbucket. When you are ready to deploy, you may also set up yet another
deploy remote, which will allow you to push your code directly to the production server. See deployment for more information.
It will help us a lot if you could star the UserFrosting project on GitHub. Just look for the button in the upper right-hand corner!
You should also follow us on Twitter for real-time news and updates:
Congratulations! Now that this is complete, you're ready to start developing your application by creating your first Sprinkle.