Development workflow/setup


I’ve been looking for documentation on how to setup Grav for developing a website but I haven’t found any clear guidelines. What I’m looking for is a setup that focuses on “developer experience” and simplicity. Here go the doubts… :slight_smile:

What goes into a GIT repository?

I’ve started a project with composer create-project, and looks like the resulting folder is what you would commit to GIT, but it’s strange to have Grav system folder (which has all the CMS code) checked in. This makes me doubt what goes into GIT.

What I’m thinking is, once the project is done, how is the process of setting the project up again on my machine? Just checkout & install composer dependencies? If this is it, what’s the upgrade history for Grav code itself?

Theme/Plugin development

Since it’s a client project and I don’t intend to share the theme or specific functionality (plugins?), where should these go? I see that in the project that composer create-project bootstraps, both the user/themes/* & user/plugins/* contents are ignored.

Should I just add GIT exceptions for my theme & plugins so they get checked in? Or is there a “community approved” best practice to manage theme/plugins? (e.g. they should go into separate repositories => although that would go against keeping it simple).

Integration with Git-Sync plugin

How does the Git-Sync plugin fit into this? My ideal would be to have my local development setup & production setup in sync via GIT (using git-flow just to not mess up prod). So, if the client updates content on prod (master) I can merge it on develop and see the real thing if need to develop new features. And once I’m done merge back to master to update production.

I don’t know if this makes any sense at all. I’m thinking that I tried the plugin and puts only the user folder (and I’m not sure if all of it) into GIT. So how does that fit with everything else (system), should the user folder be a GIT submodule? :thinking:

Deployments & backups

Here, I’m looking for advice, it’s been a long time that I don’t manage a server. So, my idea is to spin a Digital Ocean server and run it using Caddy (I don’t have experience with it, but looks like it’s the right call to keep things simple). I understand that using Git-Sync plugin, once the site is deployed and configured, subsequents updates would be handled by the plugin, is that so?

Also, related to backups, having Git-Sync, they don’t make sense anymore, do they?

Sorry if these topics are discussed/solved elsewhere, I’ve tried to research before posting. Any links related to these topics are more than welcome. Maybe is there some example project that solves these issues?

Thanks in advance!

There are multiple ways of doing this, and it’s not that uncommon to put the entire production-code into the Version Control System (VCS, ie. Git). This is the lazy equivalent to declarative environments, like Docker, where the environment for the code is included. Because Grav is flat-file, you could actually just drop the installation into Git, dependencies and all, and revive it just by cloning.

The next level is treating it pretty much like a Skeleton, where everything in /user is stored, and you declare the environment alongside. Composer is helpful here, but mostly for bootstrapping, not reproducing. There is no community-approved best practice, but there are valid concerns for dumping everything into a single repository. Declarative, semantic versioning goes out the window, whereas you really want to declare both the environment and the extensions so when reproducing you don’t have to debug as much.

The Git-Sync-plugin just creates the webhooks for automatically pushing code to the server once committed. By default it only does Pages, as I recall. I would not recommend working with Git submodules unless you are very confident with Git itself - it tends to create more overhead than you expect. Git-Sync can manage all updates to the site, including extensions, though I’d really want to limit it to Pages to avoid breaking anything with an extension-update.

For reference, here’s an example workflow with distinct environments, and an overview of a symlink-approach that might help.

For the project you describe, the symlink-approach could suit you well; have a common base installation of Grav that can rapidly be deployment in any environment. This is easy because you can download, checking, and bootstrap any version you need. Installing common extensions is as well, either by script or symlinkink folders.

Finally, keep your own extensions versioned in private repositories so you can easily sync them between environments, and symlink them into installations. Using Git-Sync for Pages is an option, but at this point I’d rather test them in Staging before moving them to Production.

This solves most of the above: You can keep a simplified manifest of what is installed where, and only need to deal with a limited set of folders. Replicating, updating, and using environments is a doddle because the architecture needed around them is largely just PHP and correct server-permissions.