Self-host Grav on a managed VPS: your flat-file CMS

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.

Simon Vasconcelos Lee By Published on 22 November 202611 minute read

All guides

In short

  1. The MIT license lets you run Grav for your company, your association or your clients with no license to buy; Grav Premium plugins are paid, and nothing here needs them.
  2. Install it with Docker Compose: the official image 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.
  3. Create the first administrator from the command line before you open the site to the internet: until an account exists, Grav offers to create it to whoever opens /admin.
  4. Behind a reverse proxy, turn on http_x_forwarded.protocol and ip in user/config/system.yaml: Grav 2 leaves them off.
  5. Back up the user/ folder with tar. Update Grav with bin/gpm selfupgrade and plugins with bin/gpm update, inside the container.

What Grav does

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.

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.

What the MIT license allows

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.

The resources to plan for

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:

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.

Installing with Docker Compose

The server needs Docker Engine and its Compose plugin. On Ubuntu, install them from Docker’s own repository:

Terminal, as root
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:

/opt/grav/compose.yaml
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:
Terminal, in /opt/grav
docker compose up -d
docker compose logs grav | tail -15
docker compose exec -u www-data grav bin/gpm version grav

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”.

The first administrator, before going public

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.

Terminal, in /opt/grav
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:

Terminal
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.

HTTPS: the reverse proxy

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.

Terminal, as root
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
/etc/caddy/Caddyfile
grav.example.com {
	reverse_proxy 127.0.0.1:8101
}
Terminal
sudo systemctl reload caddy

Telling Grav it is behind a proxy

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:

Terminal, in /opt/grav
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
Terminal
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.

The administration panel and your pages

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.

Backups

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:

Terminal, in /opt/grav
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:

Terminal, in /opt/grav
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.

Restoring

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:

Terminal, in /opt/grav
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.

Updates

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:

Terminal, in /opt/grav
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
Terminal, in /opt/grav
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.

Who does what on a managed VPS

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.

TopicOur teamsYou
The serverSystem and security updates, server interventions includedThe timing that suits you
MonitoringServer monitored 24/7, with intervention without waiting for your callYour pages, your accounts and your settings in Grav
GravProactive monitoring: errors, slowdowns and disk space spotted, fix recommendedIts installation, updates, plugins and themes, which you apply, yourself or through your AI assistant
UsersThe server that carries them, monitored and backed upAccounts and permissions
BackupsEvery night, encrypted and kept off the machine; restores includedGrav’s own archives of user/, and the restore request, when you need one
MigrationYour current server migrated, free of chargeThe 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.

Grav, on a server run for you

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.

Explore Managed VPS

Frequently asked questions

Is Grav 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.

How do I install Grav with Docker Compose?

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.

Which Grav version does the Docker image install?

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.

How do I create the Grav admin account securely?

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.

Why does Grav build http links behind my reverse proxy?

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.

How do I back up Grav in Docker?

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.

How do I update Grav in Docker?

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.

Does a managed VPS cover Grav?

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.

Contact us