We're pretty sure Statamic might be one of the simplest CMS's to get running, but there are so many different ways to run PHP apps that we need to cover a lot of bases here. Feel free to skip right to your particular dev environment. It's unlikely that everything in this article will apply to you.
Table of Contents
- The Screencast Version
- Suggested Development Environments
- Step 1: Unzip files into your webroot
- Step 2: Set permissions
- Step 3: Configure URL rewrites
- Step 4: Run the Trailhead Installer
- There is no step 5.
The Screencast Version
Visual learner? Watch how simple it is to install Statamic.
Statamic has a few system 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 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 compiled in PHP 5.5.9+ by default but we find it’s best to be thorough.
If you plan to use image Assets, you’ll need either GD or ImageMagick, and the FileInfo extension.
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: MAMP/MAMP Pro
The latest version of MAMP and MAMP Pro comes pre-loaded with Apache, PHP 5.5.9 and all the modules you need. Download, install, and go.
Mac: Laravel Valet
Laravel Valet is a development environment for Mac minimalists. No Vagrant, No Apache, No Nginx, No /etc/hosts file. You can even share your sites publicly using local tunnels. We use it, it’s brilliant.
Note: Valet supports the out-of-the-box Statamic directory structure. Subdirectory installs don’t work.
If you happen to be of the Microsoft persuasion, WAMP is a good choice, and pretty similar to MAMP. So we hear.
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 leverage lots of small files due to NFS sync delays. It’s best to not use file sharing and run Statamic directly in your VM for best results.
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
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
Let’s pause for just a moment. Do you want to run in a subdirectory for the right reason? Using Statamic in a
blog subdirectory in an existing site is one such reason. Not feeling like setting up a virtual host isn’t. We can’t stop you, but if you plan to run the site in webroot in production, you should do the same thing in development.
Professional advice given, here’s what to do:
site/settings/system.yamland change the URL from
- For any local driver based asset containers that you create, their
urlvalues will need to contain this subdirectory. (eg.
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, just use
- 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, 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.