---
title: "Building and deploying"
description: "What runs when, and the tasks you can run yourself."
url: "https://www.andromedacms.dev/docs/deploying"
updated_at: 2026-09-24
---

# Building and deploying

## The build

`andromeda:build` converts every entry into `.andromeda/`: parsed, validated,
rendered, with components expanded. It is hooked into `assets:precompile`, so
the Dockerfile that ships with Rails 8 — and therefore Kamal, and most other
deploy paths — already runs it.

`.andromeda/` is a build artifact. The installer adds it to `.gitignore` and
`.dockerignore`; it is written inside the image at build time.

## Tasks

| Task | What it does |
|------|--------------|
| `andromeda:build` | Convert everything (runs during `assets:precompile`) |
| `andromeda:check` | Report problems without writing anything — for CI |
| `andromeda:fix` | Rewrite `camelCase` frontmatter keys to `snake_case` |
| `andromeda:clobber` | Remove `.andromeda/` (runs during `assets:clobber`) |

## In development

There is no watcher to run. A file is converted the first time something asks
for it after its content changed, so editing a post and reloading is all there
is to it.

## In production

The parser never runs while serving a request; pages read the converted
result. An entry that was never built raises `Andromeda::BuildMissing`, whose
message names the task to run — a loud failure at boot beats a page that
silently converts content on the critical path.

## The database

Content needs no database. If your application has one, nothing changes; if it
does not, `andromeda:build` still runs inside a Docker build where no database
is reachable, because conversion only ever touches files.

## Troubleshooting

**`ArgumentError: wrong number of arguments (given 2, expected 1)` from
`JSON.parse`.** Not Andromeda: Rails 8.1 calls `JSON.parse` with a positional
options hash, which version 3 of the `json` gem removed. Decrypting a session
cookie goes through that path, so pages break only once a browser has a
session — which looks like "it works in a private window, and breaks when I
navigate". Pin the `json` gem until Rails ships a fix:

```ruby
# Gemfile
gem "json", "~> 2.9"
```