# Automad v2: a flat-file CMS whose content is files on disk

> Automad is a flat-file content management system and template engine written in PHP, where pages, configuration and assets live in the document root and the whole system installs from Composer, Docker or a zip. It suits developers who want to version a site's content in git, and it does not suit editors who need a multi-tenant editorial workflow.

**marcantondahmen/automad** — A flat-file content management system and template engine

- Repository: https://github.com/marcantondahmen/automad
- Website: https://automad.org
- Stars: 962 · Forks: 62
- Language: PHP
- License: NOASSERTION
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/marcantondahmen-automad

## Content as files is the whole premise, not a storage optimisation

Automad is described in one line as a flat-file content management system and template engine, and the flat-file part is the design, not a fallback mode. Pages live in a pages directory, configuration in a config directory, and both sit inside the document root where the web server can reach them.

That choice has consequences in both directions, and it is worth being clear about them. On the positive side, a site becomes a set of files that can be committed to git, reviewed in a pull request, backed up with rsync, and moved between machines by copying a directory. There is no database to migrate, no schema to design, and no export step when a project ends. For a small site or a documentation site, that is a genuinely better fit than a stack you have to keep alive.

On the negative side, the flat-file model constrains how you query and relate content. There is no join across pages in a database sense, and the template engine is what you use to present and traverse content instead. That is a deliberate trade: you gain simple deployment and lose the query layer that a relational store provides.

The audience implied by all this is developers and technically confident editors who want to be close to their content. The project ships a template language with editor plugins for Neovim through Tree-Sitter, Visual Studio Code, Atom and Textmate 2, which is a strong hint about who is expected to write the templates.

## Three installation paths, and the source repository holds only source code

The first thing to understand is that the repository you are looking at does not contain a runnable site. The documentation says so directly: this repository only contains source code, and to get a fully bundled version you should use Docker or Composer, or download a distribution bundle.

Composer is called the fastest route.

```bash
composer create-project automad/automad . v2.x-dev
```

The version constraint is v2.x-dev, which tells you something about the release posture of the current line.

The Docker route runs a container that bundles Nginx and PHP 8.3.

```bash
docker run -dp 80:80 -v ./app:/app --name mysite automad/automad:v2
```

The site is then reachable on port 80, and a directory called app in your working directory is mounted for data persistence. A new user account for the dashboard is created automatically, and the credentials are written to the container log, which you read with the logs command.

```bash
docker logs mysite
```

After that you open localhost in a browser.

The manual route is three steps. Download a distribution bundle, move the unpacked content to the document root of your web server, make sure the PHP process can write to the document root and its subdirectories including all installed files, then visit the /dashboard route and create the first user. If you cannot use Docker or Composer, that is the documented path, and the write permission requirement is the part that trips people up on shared hosting.

## The v2 line is still a beta, and the tags move daily

The release history tells you exactly where the project is. The most recent tags are 2.0.0-beta.68 on 2026-10-18, 2.0.0-beta.67 on 2026-10-17, and 2.0.0-beta.66 on 2026-10-17. The package.json in the repository carries the same version string, 2.0.0-beta.68, and the default branch of the repository is v2.

Three beta tags in two days is normal for a pre-release train, and it is also a real operational consideration. There is no tagged stable 2.0 release in that list, and the Composer command in the documentation asks for v2.x-dev, which is a moving target. If you pin your production site to a beta tag, you pin it to a specific artifact, and you upgrade deliberately. If you follow v2.x-dev, you take whatever shipped that day.

The activity itself is not in question. The last push was on 2026-10-18, the repository is not archived, and the CHANGELOG.md in the repository is linked from the project page as the place where changes are recorded.

One contributing rule is worth knowing before you plan around upstream. The project states that pull requests to this repository are not accepted and will not be merged. The welcome list is narrower: improving the language packs, giving feedback, reporting bugs and feature requests, and reporting security vulnerabilities. Code contributions are not part of that list, which tells you the upstream accepts fixes through a different path or not at all.

## A template language with a toolchain behind it

The template engine is the part of Automad that a developer actually touches, and the surrounding toolchain shows it is taken seriously. The repository root contains a package.json, a package-lock.json, an esbuild.js bundle script, a postcss.config.js, a tsconfig.json, a vitest.config.js, a phpunit.xml, a psalm.xml and a psalm-autoloader.php, alongside a .php-cs-fixer.php configuration.

The npm scripts are a good map of the development workflow.

```json
    "build": "npm run prebuild && node esbuild.js",
    "test": "npm run phpunit && npm run psalm && npm run typecheck && npm run vitest",
    "typecheck": "tsc --noEmit",
```

The test command chains four separate gates: PHPUnit for the PHP side, Psalm for static analysis, tsc for the TypeScript side, and Vitest for the JavaScript tests. There are also scripts for a dev server, a dev Docker setup, a mailpit container for local mail testing, an MCP inspector, a release script, and a helper that finds unused code.

For a CMS, that is an unusual amount of engineering investment, and it explains the theme story. Themes are built with the same tooling, which is why editor plugins with syntax highlighting and snippets exist for four different text editors. A designer working on Automad templates is expected to have a proper language server experience rather than guess at tag names.

## Configuration lives in config.php, and .env files are for local machines only

The configuration story is explicit about where settings should live, and the warning at the top of the .env.example file is the clearest statement of intent in the repository: do not use .env files on production servers, and .env files should only be used during development on local machines. A production site is configured by setting environment variables in the web server configuration or in the config.php file instead.

The .env.example file also explains the scope of the environment approach. While all available settings can be defined inside config.php, only a subset can be set as environment variables, and the list is prefixed so you can tell them apart at a glance.

```bash
AM_ALLOWED_FILE_TYPES=
AM_CACHE_ENABLED=
AM_CACHE_LIFETIME=
AM_DEBUG_ENABLED=
AM_DISK_QUOTA=
AM_MAIL_TRANSPORT=
AM_MCP_SERVER_ENABLED=
AM_PASSWORD_MIN_LENGTH=
```

Two settings deserve attention. AM_DISK_QUOTA is the kind of limit that matters on a shared host, where an unbounded upload directory is a nuisance for whoever else lives on the machine. And AM_MCP_SERVER_ENABLED together with AM_MCP_SERVER_URL points at a Model Context Protocol server surface, which is a new and less documented corner of the system.

Secret handling is handled separately, and the file says so. There is an AM_ENCRYPTION_KEY for config files, with the comment that it is not exposed as a constant in Automad, that leaving it empty disables encryption, and that you should never use the .env file in production but set the key as an environment variable in the web server or .htaccess file instead. A key file alternative is available through AM_ENCRYPTION_KEY_FILE, and the documentation points to docs/encrypting-secrets.md.

## What a flat-file CMS gives up against a database-backed system

The honest comparison here is with a conventional CMS backed by a relational database, and the difference is in the data model rather than in the feature list.

A database-backed system stores pages as rows and lets you query across them: all pages tagged X published after date Y, sorted by a custom field. Automad stores the same content as files, so the equivalent operation is expressed in the template language rather than in SQL. The trade is real in both directions. Queries are bounded by what the template language can express, and a large site with many content types can become awkward to organise, because the structure is a directory tree rather than a set of tables. In exchange, deploys are file operations, backups are copies, and a broken database migration is a category of problem you simply do not have.

There is a second difference that catches people: write permissions. The manual installation explicitly requires that the PHP process can write to the document root and its subdirectories, including all installed files. On a hardened host where the web server user is not allowed to write anywhere, that instruction turns into a support ticket, and the fix belongs in the server configuration rather than in loosening permissions across the tree.

A third gap is editorial workflow. The project describes a dashboard and user accounts, but the flat-file model, with content as documents in a tree, is built for a small number of trusted editors rather than a newsroom with dozens of roles, staged publishing and scheduled changes.

## Licence, live demo, and a 2.0 line that has not settled

On the licence, the metadata does not give you a standard identifier, and the project points to a file instead. The footer of the project page says to see LICENSE.md for licence information, and the copyright line reads 2013-2026 Marc Anton Dahmen, so this is a long-running project with a single named author rather than a foundation effort. Read LICENSE.md for the actual terms before you build a business on it, and note that this is not legal advice.

For evaluation, the project offers a live demo at try.automad.org. The documentation says there is no sign-up required and that you get your own demo instance to explore features in. That is a good way to test the template language and the dashboard before you commit to an installation, and it costs nothing but a browser.

The docs, the discussion platform and the changelog all live alongside the project, and the developer toolchain described earlier is what you inherit if you go further. What you are adopting in practice is a 2.0 release line that is still tagged as a beta, with a 2.0.0-beta.68 artifact as the current release, daily tag movement, a source repository that does not accept pull requests, and a custom licence file that the ecosystem metadata cannot classify. That combination suits a developer who wants files on disk and a template language, and it asks for a sober reading of the licence and the beta status before it goes in front of visitors.

## Conclusion

Adopt Automad when a site should live as files in a repository and be edited through a template language rather than a database schema, and when you are comfortable with a 2.0 beta release line. Do not adopt it if you need a stable, tagged release, because the current tags are 2.0.0-beta.66 through beta.68 and the project states that pull requests to the source repository are not accepted. Before committing, read LICENSE.md rather than relying on the licence metadata, decide whether the 2.0.0 beta.68 API surface is acceptable for production, and confirm that your PHP process can write to the document root, which the manual install instructions require.

## FAQ

### How do I install Automad?

The fastest route is Composer, with composer create-project automad/automad . v2.x-dev, and a Docker image is also published that bundles Nginx and PHP 8.3. For a manual install, unpack a distribution bundle into the document root, give the PHP process write permission there, and create the first user at the /dashboard route.

### Does Automad need a database?

No. Automad is a flat-file content management system, so content is stored as files in the document root, with a pages directory and a config directory. Deployment and backup are file operations rather than database migrations.

### Is Automad 2.0 stable yet?

Not according to the tags. The recent releases are 2.0.0-beta.66, 2.0.0-beta.67 and 2.0.0-beta.68, dated 2026-10-17 and 2026-10-18, and the Composer command in the documentation requests v2.x-dev.

### Can I use .env files in production for Automad?

The .env.example file states that .env files should only be used during development on local machines, and that a production site should be configured through environment variables in the web server configuration or through config.php. Only a subset of settings can be set as environment variables at all.

### How do I contribute to Automad?

The project states that pull requests to the source repository are not accepted and will not be merged. Accepted contributions are improving the language packs, giving feedback, reporting bugs and feature requests, and reporting security vulnerabilities.

## Sources

- [Issues](https://github.com/marcantondahmen/automad/issues)
- [marcantondahmen/automad on GitHub](https://github.com/marcantondahmen/automad)
- [Project website](https://automad.org)
- [README](https://github.com/marcantondahmen/automad/blob/v2/README.md)
- [Releases](https://github.com/marcantondahmen/automad/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/marcantondahmen-automad