You should almost never download individual files via FTP, edit them, and then upload them—overwriting the older copies on a server. This is a generally outdated practice and something I still see used frequently when people don’t know of a better option, are too lazy to change, or maybe just in a hurry. It’s also very prone to errors, and if you overlook something and overwrite a file without a backup copy, well—you’re screwed. This is also why the entirety of modern development workflows rely on version control systems, like Git.
The correct way to do development for your blog is to have two copies of your website: your production copy (the site that is live on the web), and your development instance (the mirrored copy that you actually modify and develop, that lives on your local machine). Since Grav was designed for developers, there are some great ways to get started with this kind of environment. Here is a fast route to getting up and running:
- Create a new droplet on DigitalOcean (~$5/month) that is running a fresh copy of Grav with the default theme, and the Grav Admin plugin (the Admin plugin is essential to this tutorial).
- Log in to your new Grav blog and click the “backup” button on the “Maintenance” section of the Dashboard. This will create a downloadable archive of your entire Grav install, including the often overlooked .htaccess files (you should always ensure that these are viewable, since many operating systems and SFTP programs hide them by default).
- Download this archive and unzip it into a directory on your local machine that you plan to use for development work. Again, if you copy the extracted files to another directory via Finder (or similar), and not with the command line (Terminal), you may not copy over the hidden .htaccess files, and your local Grav site won’t load. Just rename the directory and move the entire directory to the place that works best for you.
- Once you have these files all nice and neat on your local machine, install MAMP or WAMP (if you haven’t already). I am using MAMP—since I’m on a Mac.
- Open up MAMP and make sure that you’re loading the new development folder when you run your local server (known as Document Root).
- Change your local server from Apache to NGINX. This step will depend on which server you are running in production—but isn’t mission critical. I like to precisely mirror every component between production and development, so I don’t encounter weird hard-to-track errors. Both should work fine.
- Change your Grav config files (this step is optional but must be done if your production server is using an SSL certificate). Grav has a great option to force SSL, which ensures every page is loaded securely, but since you aren’t running an SSL cert on your development machine, your blog won’t load in MAMP at all until you change this. Strictly speaking, the only file that should differ between your production server and development machine is the config file (assuming you aren’t changing things as of yet). Also, Grav, like CSS, will recognize overrides, so make sure that the config file you change is the one that Grav is actually referencing. For me, this system config file was located under: “user/localhost/config/system.yaml” and you should set the “force_ssl” option from “true” to “false.” Again, if you aren’t using SSL yet, skip this step, if you are, and don’t make this change, your entire site will fail to load, and you will feel like a crazy person.
- Load your site with MAMP (or WAMP). Everything should load fine, and if it doesn’t, make sure your MAMP preferences are pointing to the main Grav directory on your local machine. You can try restarting MAMP (or your computer) if this still doesn’t work. Otherwise, you probably did something wrong.
- Once you have a mirrored copy of your production site running on your local machine, you can edit it as necessary, and push the changes to your server (via SFTP, for example). A good step at this point would be to make sure you’ve installed Git on your server and have committed a copy of your fresh production install. You can then use a typical Git workflow to checkout your code and push new changes (or revert) as needed. This step also isn’t absolutely critical, especially if you’re unfamiliar with Git, or running a site that will change very infrequently, but it’s a great next step.
Hopefully this will help anyone who is out there working on their Grav blogs to create a nice mirrored development setup, so they don’t accidentally overwrite files on a live site, or edit files on their production servers; directly.
Nick is the Founder & CEO of MetaSensor, a venture-backed internet of things startup located in Silicon Valley, and a Behavioural Product Designer at Duke's Center for Advanced Hindsight (with Dan Ariely et al.). | Read Full Bio »
Intro to the Immutable Log
The Immutable Log, which is a term I first came across while reading an article in Forbes many years ago, is such an amazing concept—yet virtually nobody …