To self-host Grav on a managed VPS is to keep your website, its pages and its accounts on a server of your own, which our teams keep up to date and monitor day and night. Grav is a free, open source flat-file CMS under the MIT license: your content lives in Markdown files, with no database to run. This guide follows its official Docker image with Grav 2.2.32, the latest release, and we ran every command on a Simafri VPS before writing it: installation with Docker Compose, the first administrator, HTTPS, backups, a restore and updates.
By Simon Vasconcelos Lee
Published on 22 November 202611 minute read
getgrav/grav:php8.4, one named volume for the whole site, and port 8101 published on 127.0.0.1 behind an HTTPS reverse proxy./admin.http_x_forwarded.protocol and ip in user/config/system.yaml: Grav 2 leaves them off.user/ folder with tar. Update Grav with bin/gpm selfupgrade and plugins with bin/gpm update, inside the container.Grav is a content management system written in PHP that stores everything in files: each page is a folder with a Markdown file, and the configuration and the accounts are YAML files. There is no database to install, tune or back up, which makes a Grav site easy to copy, version and restore.
/admin on top of Grav’s own REST API, with a dashboard, a page editor, media, users and configuration.Grav 2 is the current line and needs PHP 8.3 or later. The 1.7 line still receives maintenance releases, and moving a 1.7 site to Grav 2 is a migration rather than an in-place upgrade: the Grav documentation describes it step by step. This guide installs Grav 2 from the start.
Grav is published under the MIT license. You can use it free of charge, for your company, your association or your clients, copy it, modify it and redistribute it, as long as the copyright notice and the license text stay with it. The software is provided without warranty.
The plugins and themes of the GPM repository each have their own license. Grav Premium plugins, published by the Grav team, are paid. Nothing in this guide needs them.
Grav asks for little: a web server and PHP 8.3 or later, with a user cache such as APCu recommended. Here is what we measured on our test VPS, with Grav 2.2.31 and its sample pages:
user/ took 13 MB, plugins and themes included; your images and files add to it.Server size therefore depends on your traffic and on the other applications you run beside Grav. On a managed VPS, tell us about your usage and we will recommend the right size.
The server needs Docker Engine and its Compose plugin. On Ubuntu, install them from Docker’s own repository:
apt-get update -qq && apt-get install -y -qq ca-certificates curl >/dev/null && install -m 0755 -d /etc/apt/keyrings && curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc && chmod a+r /etc/apt/keyrings/docker.asc && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo $VERSION_CODENAME) stable" > /etc/apt/sources.list.d/docker.list && apt-get update -qq && DEBIAN_FRONTEND=noninteractive apt-get install -y -qq docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin >/dev/null && docker --version && docker compose version
The official image, getgrav/grav, contains PHP, Apache and the extensions Grav needs. When its volume is empty, it downloads the latest stable Grav with the Admin from getgrav.org on its first start; afterwards, it leaves the site as it is. Create a folder such as /opt/grav and put this compose.yaml in it, based on the example of the image:
services:
grav:
image: getgrav/grav:php8.4
restart: unless-stopped
ports:
- "127.0.0.1:8101:80"
volumes:
- grav_site:/var/www/html
volumes:
grav_site:
docker compose up -d
docker compose logs grav | tail -15
docker compose exec -u www-data grav bin/gpm version grav
php8.4 tag: the image comes in php8.3 (also latest), php8.4 and php8.5. The tag names the PHP version, not the Grav version: Grav itself is installed in the volume and updated with GPM.127.0.0.1: the example of the image publishes port 8080 on every address of the server. Published locally, Grav is reachable only through the reverse proxy.grav_site, holds the whole site, including user/ with your pages, accounts, configuration, plugins and themes. The Grav documentation asks that user be persisted at the very least.bin/grav scheduler every minute, as www-data. On our VPS, it listed log rotation, cache cleanup and a default-site-backup job planned for 03:00 every day.www-data: the files belong to the Apache user, so every Grav command runs with -u www-data.On our test VPS, the first start installed Grav in about ten seconds, and the version command answered “You are running Grav v2.2.32”.
Until an account exists, every page of a new Grav 2 site redirects to /admin, which offers to create the first administrator to whoever opens it. Create yours from the command line while Grav is still reachable only on 127.0.0.1, then put HTTPS in front of it.
docker compose exec -u www-data grav bin/plugin login new-user -u admin -e admin@example.com -P b -l en -N "Site Admin" -t "Administrator"
The command asks for the password twice; it must have at least eight characters, with a number, a lowercase and an uppercase letter. With Admin Next installed, the account receives the api.super permission that the panel uses, and site.login. Once it exists, the site serves its home page instead of the redirect:
curl -s -o /dev/null -w "/ -> %{http_code}\n" http://127.0.0.1:8101/
On our VPS, the answer went from 302 to 200, and Grav’s API reported that setup was no longer required.
The container serves Grav over HTTP, on port 8101 of the server. HTTPS is handled by a reverse proxy in front of it. We tested Caddy, installed from its official repository for Debian and Ubuntu: it obtains the Let’s Encrypt certificate itself, renews it, and sends the X-Forwarded-Proto and X-Forwarded-For headers, replacing any that a visitor might send.
DEBIAN_FRONTEND=noninteractive apt-get install -y -qq debian-keyring debian-archive-keyring apt-transport-https gnupg >/dev/null && curl -1sLf https://dl.cloudsmith.io/public/caddy/stable/gpg.key | gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg && curl -1sLf https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt > /etc/apt/sources.list.d/caddy-stable.list && chmod o+r /usr/share/keyrings/caddy-stable-archive-keyring.gpg /etc/apt/sources.list.d/caddy-stable.list && apt-get update -qq && DEBIAN_FRONTEND=noninteractive apt-get install -y -qq caddy >/dev/null && caddy version && systemctl is-active caddy
grav.example.com {
reverse_proxy 127.0.0.1:8101
}
sudo systemctl reload caddy
Grav 2 ignores the X-Forwarded-* headers by default, so that a visitor cannot pass off a false address or protocol. Behind Caddy, it therefore believed it was served over plain HTTP: on our VPS, the Link header of the home page pointed to http:// and the session cookie was not marked secure. Turn on the two headers that Caddy sets, in the site’s configuration:
docker compose exec -T -u www-data grav tee -a user/config/system.yaml >/dev/null <<EOF
http_x_forwarded:
protocol: true
ip: true
EOF
curl -sI https://grav.example.com/ | grep -i -E "^(link|set-cookie):"
curl -s https://grav.example.com/ | grep -o -E "<h1[^>]*>[^<]*</h1>"
Grav reads its configuration again on the next request. On our VPS, the Link header then pointed to https://, the cookie was marked secure, HttpOnly and SameSite=Lax, and the home page, titled “Home | Grav”, answered with its heading “Say Hello to Grav 2.0!”. protocol and ip are enough with Caddy, which passes the original Host header as it is.
Apache, in the container, applies the .htaccess file that comes with Grav. We checked it through HTTPS: user/config, user/accounts, system/config, logs, cache, bin, backup, the Markdown files of user/pages and .htaccess itself all answered 403, and a missing page 404.
Open https://grav.example.com/admin and sign in with the account you created. On our test VPS, in a real browser, Admin Next showed its dashboard, with “Grav v2.2.32 · Admin v2.2.16” at the bottom of the sidebar, and a wrong password left us on the sign-in page.
user/pages with a Markdown file: a page we wrote that way, from the command line, appeared in the list at once.With no database, a Grav site is its user/ folder: pages and their media, accounts, configuration, plugins, themes and data. Everything else is Grav itself, which the image can install again. Keep your compose.yaml with it. The image includes tar; create the archive readable by root only:
umask 077
docker compose exec -T grav tar -C /var/www/html -czf - user > grav-user-$(date +%F).tar.gz
umask 022
ls -l grav-user-*.tar.gz
Schedule this copy and send it off the server. Stored on the disk, the archive is also included in the server’s nightly backups.
Grav also has its own backup command, which archives the whole site, except its backups, caches, images, logs and temporary files, into the backup folder of the volume. Copy the archive out of it, here the one our VPS produced:
docker compose exec -u www-data grav bin/grav backup
docker compose cp grav:/var/www/html/backup/default_site_backup--20261120032915.zip .
On our VPS, it archived 6,366 files in two seconds, 22 MB. The default-site-backup job of the scheduler writes the same archive every night into the volume, on the server itself: it is no substitute for a copy kept elsewhere.
On the same installation, or on a new one with the same compose.yaml where docker compose up -d has installed Grav, stop the container, replace user/ with the archive, then start it again and clear the cache. Run the commands one by one, and stop if one of them fails:
docker compose stop grav
docker compose run --rm --no-deps --entrypoint rm grav -rf /var/www/html/user
docker compose run --rm --no-deps -T --entrypoint tar grav -C /var/www/html -xzf - < grav-user-2026-11-20.tar.gz
docker compose up -d
docker compose exec -u www-data grav bin/grav clearcache
We tested the whole cycle on our VPS: a page written before the archive, then the volume deleted with docker compose down -v and created again empty, where the image installed a new Grav, then the restore. The page came back over HTTPS with its text, the administrator signed in again with the same password, and the files kept their owner, www-data.
Grav publishes maintenance releases often, several a week at times, and lists them on GitHub. The Grav Package Manager updates Grav itself, then the plugins and themes, inside the container. Take a backup, then run:
docker compose exec -u www-data grav bin/gpm selfupgrade -f -y
docker compose exec -u www-data grav bin/gpm update -f -y
docker compose exec -u www-data grav bin/gpm version grav
selfupgrade downloaded the 8 MB update, staged it, installed it and answered “You are running Grav v2.2.32”. The page, the administrator and the admin panel were all there afterwards. Without -y, the command asks before it proceeds.bin/gpm update found four plugins to update, Email, Flex Objects, Form and Login, updated them and cleared the cache. The Updates widget of the Admin Next dashboard lists them too, with an Update All button.docker compose pull then docker compose up -d bring the latest build of the tag, with PHP, Apache and Debian updates. The image is rebuilt every week and at each Grav release; it does not change the Grav in your volume.docker compose pull && docker compose up -d
On our VPS, the image we had just pulled was already the latest build: Compose kept the container running, and the site answered as before.
Self-hosting means running the server on top of the application. On a managed VPS, our teams take charge of the server and proactively monitor your instance; Grav remains your software, with your content and your settings.
| Topic | Our teams | You |
|---|---|---|
| The server | System and security updates, server interventions included | The timing that suits you |
| Monitoring | Server monitored 24/7, with intervention without waiting for your call | Your pages, your accounts and your settings in Grav |
| Grav | Proactive monitoring: errors, slowdowns and disk space spotted, fix recommended | Its installation, updates, plugins and themes, which you apply, yourself or through your AI assistant |
| Users | The server that carries them, monitored and backed up | Accounts and permissions |
| Backups | Every night, encrypted and kept off the machine; restores included | Grav’s own archives of user/, and the restore request, when you need one |
| Migration | Your current server migrated, free of charge | The timing of the switch |
If you would rather have our teams work inside the application itself, that service is billed by the hour or at a fixed rate, with an estimate shared before the work starts.
With a Simafri Managed VPS, our teams keep your Grav site’s server up to date, monitor it day and night and step in without waiting for your call; they also proactively monitor your instance and recommend useful fixes, which you apply, yourself or through your AI assistant. Backups are encrypted every night and kept off the machine, restores are included, and migrating your current server is free.
Yes. Grav is under the MIT license: you can run it for your company, your association or your clients with no license to buy. Grav Premium plugins are paid, and nothing in a basic site needs them. What remains is the cost of the server that runs it.
Use the official getgrav/grav image, with a PHP tag such as php8.4, and a named volume on /var/www/html in a compose.yaml. Publish port 80 of the container on 127.0.0.1, run docker compose up -d, create the first administrator with bin/plugin login new-user, then put an HTTPS reverse proxy in front.
The latest stable Grav with the Admin, downloaded from getgrav.org when the volume is empty: Grav 2.2.32 when we tested. The image tag only names the PHP version. After the first start, the image leaves your site alone, and Grav is updated with bin/gpm selfupgrade.
Before the site is public. A new Grav 2 site redirects every page to /admin, which offers to create the first administrator to whoever opens it. Run bin/plugin login new-user in the container while Grav is published on 127.0.0.1 only, then set up HTTPS.
Grav 2 ignores X-Forwarded headers by default. Add http_x_forwarded with protocol: true and ip: true to user/config/system.yaml when your proxy sets these headers, as Caddy does: Grav then builds https links and marks its session cookie secure.
Archive the user folder from the container with tar, under umask 077, and keep your compose.yaml. To restore, stop the container, replace /var/www/html/user with the archive, start it again and clear the cache. bin/grav backup also archives the whole site into the backup folder.
Take a backup, then run bin/gpm selfupgrade -f -y and bin/gpm update -f -y in the container, as www-data. Pulling a newer image updates PHP and Apache, not Grav. Moving from Grav 1.7 to Grav 2 is a migration, described in the Grav documentation.
A managed VPS covers the server: system, security, monitoring and backups. Our teams also proactively monitor your instance and recommend useful fixes, which you apply. Work inside the application is billed by the hour or at a fixed rate.
Simafri
Let's talk about your project
Tell us what you need in a few words: we will get back to you quickly.
Thank you! Your request has been sent. We'll get back to you shortly.
Prefer email? Write to us at support@simafri.com.