Statamic is one of the simplest web applications to get up and running, but there are many different ways to run PHP apps, so we'll cover a lot of variations here. Feel free to skip around until you find your particular dev environment. It's unlikely that everything in this article will apply to your personal style.
The Screencast Version
Are you a visual learner? Watch how to install Statamic.
Statamic has a few server requirements. Not all servers are created equal and not all hosts play nice. Statamic v2 is built on Laravel, so as a rule of thumb — anywhere Laravel 5.1 runs, Statamic runs. You can even use Forge + Digital Ocean. We do, and we love it. Anyway, here’s what you’re going to need.
- A web server: Apache, Nginx, or IIS
- PHP >= 5.5.9
- URL Rewriting enabled (mod_rewrite, try_files, etc)
Required PHP Extensions
These should all be included in PHP 5.5.9+ by default, but in case you’re a tinkerer, you’re going to need these:
Optional (But Recommended)
Suggested Development Environments
You can (and probably should) run Statamic locally while you develop your site. There are a number of solutions that give you all the tools you need without having to compile anything by hand.
If you’re into that though, all the better. You can probably skip over the rest of this section.
Mac: Laravel Valet Our Favorite!
Laravel Valet is a development environment for Mac minimalists. No Vagrant, No Apache, No Nginx, No need to manually edit hosts file. It simply maps all the subdirectories in a “web” directory (such as
.localhost domains. You can even share your sites publicly using local tunnels with a single command. We use it ourselves and it’s brilliant.
Valet only supports running in web root out of the box, but if you need to run in a subdirectory you should check out the LionsMouth Valet Driver
Mac: MAMP/MAMP Pro
If you prefer a GUI interface, the latest version of MAMP and MAMP Pro comes pre-loaded with Apache, up to date versions of PHP and all the modules you need. Download, install, and go.
If you happen to be from the Microsoft camp, we hear WAMP is a good choice, and pretty similar to MAMP. We don’t do Windows so we can’t vouch for it personally.
Prefer a virtual environment? You’re in luck, Laravel Homestead is a pre-packaged Vagrant “box” that provides you a wonderful development environment without requiring you to install PHP, HHVM, a web server, or any other server software on your local machine. No more worrying about messing up your operating system! If something goes wrong, you can destroy and re-create the box in minutes.
Homestead runs on any Windows, Mac, or Linux system, and includes the Nginx web server, PHP 5.6, MySQL, Postgres, Redis, Memcached, Node, and all of the other goodies you need to develop amazing Laravel applications.
Note: Homestead is not a fast local dev environment for applications that manage lots of small files due to NFS sync delays. For best results avoid file sharing and run Statamic directly in your VM.
You can try enabling NFS to speed up Homestead. In your
type: "nfs" to your
folders: - map: ~/Code to: /home/vagrant/Code type: "nfs"
Statamic doesn’t support Laravel’s native
serve command, but you can use PHP’s CLI Server (for which the
serve command is just a wrapper for). You must
statamic/server.php to use as a router file.
$ php -S localhost:3000 statamic/server.php PHP 5.6.10 Development Server started at Thu Jan 21 10:30:00 2016 Listening on http://localhost:3000
Command Line Installation
First, download the Statamic CLI tool using Composer. You only have to do this once.
Once installed, the
statamic new command will create a fresh Statamic site in the directory you specify.
statamic new awesome-site
This will download and install Statamic into the
Grab the latest version of statamic and let’s do this.
Step 1: Unzip files into your webroot
Unzip your Statamic package into your web root. You’ll see the following folders and files:
webroot/ |-- assets/ |-- local/ |-- site/ |-- statamic/ |-- index.php |-- please |-- robots.txt |-- sample.gitignore |-- sample.nginx.conf |-- sample.htaccess |-- sample.web.config
Running in a subdirectory
Subdirectory installs are a little special. We’ve dedicated a whole page to it!
Step 2: Set permissions
Every Statamic instance needs full write access to the following 4 directories recursively (e.g. all their subfolders and files).
In order to have write access, the necessary permissions depend on which system user PHP is running as and which user owns the files and folders. Here are some recommendations. When in doubt (or on dev), throw caution to the wind with
- If they are the same user, use
- If they are the same group, use
- If they are neither the same user nor in the same group, or if you’re tired of messing with this and you’re still in dev, just use
Apply the permissions recursively so Statamic can write where it needs to.
The simplest way to apply the permissions is to use the following command. (You may need to use
chmod -R 777 site local statamic assets
Step 3: Configure URL rewrites
Like most (if not all) PHP applications, all page requests are run through a single
index.php file called a “front controller”. This allows the page to be dynamically displayed from the CMS.
Technically this means all your URLs are actually
/index.php/about but they will get rewritten to
/about. It’s better for SEO, and the
index.php just looks silly, so you should remove it.
Note: Out of the box, Statamic will assume you will be using URL rewrites. If you notice only your home page working, it’s usually because URL rewrites aren’t configured. Either set them up, or read how to disable them at the end of this section.
Most decent servers will support URL rewriting in some way. Choose your method below:
Make sure you have
mod_rewrite enabled and rename the
sample.htaccess file to
.htaccess, taking special care to ensure that it’s in the same directory as your
index.php file. They’re best friends, don’t separate them.
If this doesn’t work, you’re most likely someone who doesn’t follow defaults and runs your own flavor of configuration. Google is your friend. If you’re really stuck, we’ll do our best to help you.
Grab the settings from
sample.nginx.conf and customize them as necessary. Nginx is a bit less “set it and forget it” than Apache, making further server configuration beyond the scope of this guide.
We don’t use Windows ourselves, but we’ve been told the included
sample.web.config works. Do your thing.
Disabling URL Rewrites
If for whatever reason you can’t or don’t want to use URL rewriting, you can configure Statamic to leave
index.php in your URLs.
site/settings/system.yaml, and add
Step 4: Run the Trailhead Installer
Technically there is no “install” process for Statamic, but we have a little tool that will check your environment for all the necessary requirements, file permissions, locales, and even help you get your first User created. Head to
/installer.php and let it take care of the rest for you.
Once you’re done, delete
If you don’t want to (or can’t for some reason) use the GUI installer, here’s what to do yourself:
- [Create an admin user][create-user]
- Log into the Control Panel at
- Visit your System settings (/cp/settings/system) and set/confirm your basic site settings
There is no step 5.
You’re probably done. Now for some things to note, and a few additional steps for running above webroot and multilingual sites.
About that License Key and Dev Mode
If you don’t have a license key, that’s okay! You can use Statamic in developer mode for as long as you’d like in your local environment. Just be sure to purchase and add the key to your system config before you launch, otherwise you won’t be able to access your control panel.
Site URL and Permalinks
Out of the box, Statamic will only use relative URLs as a way to get things going smoothly. However if you want to use permalinks (full URLs that
include your domain) you’ll need to adjust it in
site/settings/system.yaml in the
locales array. Change the
url from a relative
to a full URL like
http://mysite.com/. If you ran the installer, you’ve probably already done this.
Moving Statamic Above Webroot (optional)
For extra security you can move your system files above webroot. This prevents system files from potentially being accessed through a browser.
If you’d like to support multiple languages, head over to Localization for a few additional steps.