This page covers where settings go, how Raster decides whether it's running in development or production, the page cache, and the full list of settings and environment variables.

Your settings live in application/config/the_app.php, written like this:

<?php
config::set('theme')->to('default');
config::set('protected')->to(array('account' => 'member'));
config::set('after_login')->to('account');

This file is loaded after the framework's defaults (system/config/app.php), so what you set wins. Read a setting anywhere with config::get('name'), or config::get('name', $default). You can add settings of your own the same way; the demo café keeps its staff email address in config::set('cafe_staff_email').

Other files in application/config/:

Secrets (SMTP passwords, tokens) are better kept out of these files and out of git: use environment variables, listed at the end of this page.

An environment is a name for where the site is running. Raster uses two:

You can define more environments (such as staging): add a matching config/db/staging.php.

1. If the environment variable RASTER_ENV is set, it wins. Set RASTER_ENV=production on every server.

2. Otherwise the host name of the request is looked up in application/config/servers.php:

   <?php
   $servers['localhost'] = 'development';
   $servers['127\.0\.0\.1'] = 'development';
   $servers['staging\.example\.com'] = 'staging';

   Keys are regular expressions matched against the whole host name (without the port). localhost and 127.0.0.1 only count when the request really comes from the same machine, so nobody can switch your live site into development by sending a fake Host header.

3. A host that isn't listed is production.

4. Without a servers.php file, everything is development.

On the command line there is no request, so Raster uses the host from RASTER_URL, or localhost when it isn't set. That makes commands run in development by default. Setting RASTER_URL=https://example.com/ alone therefore also switches a command to production (the host isn't listed). To be explicit, set RASTER_ENV:

RASTER_ENV=production php bin/raster schema --apply

Set it for production:

RASTER_URL=https://example.com/

or config::set('site_url')->to('https://example.com/'). With it, every link Raster builds (in pages, emails, feeds, sitemaps) uses that address rather than the Host header the visitor's browser sent. In production, emails with links are not sent without it, and raster send requires it. On the command line it also tells commands like render and user which address to print.

In production, whole pages are saved and sent again to the next visitor without running any PHP models. This makes the site fast on small servers.

• Only pages for visitors without a session (not logged in) and without a query string are cached. /api, /mcp and /login never are.
• Tracking parameters don't count as a query string. A link shared as /about?utm_source=newsletter (any utm_*, or the click ids fbclid, gclid and msclkid) gets the cached /about, and is made the way /about is: the tracking values are left out of $_GET, so they never end up in the page other visitors get (in a pagination link, say). Any other parameter skips the cache.
• Any content change clears the whole cache: a save in the editor, over MCP or from the command line. The cached files are deleted then, so the folder only holds pages for the current content. When a scheduled item's publish time arrives, the cache is cleared too. A page that was being made while the content changed is not kept.
• Lists nobody can fill aren't cached. A filter page with no items (/news/news_items/tag/nothing), a page number past the last one (/news/news_page/999) and a filter on a field the list doesn't have still answer 200, but are never kept. Neither is a list or item address spelled other than the way the site's own links spell it: /news/news_page/1 or /news/news_page/02 for a page, /news/news_item/007 for item 7, or a segment left over at the end. The same goes for a filter on a number, date or yes/no field written another way than the page prints it: /menu/menu_items/price/14.500 when the price shows as 14.50, or /events/events_items/date/10 Oct 2026 for 2026-10-10. Nor is a view name in other letter case: on a disk that ignores case (macOS, Windows) /ABOUT or /News/news_page/2 finds about.html or news.html and answers, but only the file's own spelling is kept. All of them are kept out so a crawler trying made-up addresses can't fill the disk. A model of your own that knows its page shouldn't be kept calls raster_cache::skip().
• If your own model changes data that pages show, call util::content_changed() afterwards.
• Changes made outside Raster don't clear it: a view, theme file, model or config edited in a text editor (or by an agent with plain file tools), or the database changed directly. Visitors who aren't logged in keep seeing the old page until the cache is cleared or page_cache_ttl runs out. Clear it with php bin/raster cache clear, or the MCP tool clear_cache. raster render and MCP render_url never read the cache, so they show the change before visitors do.
• Responses carry an X-Raster-Cache: hit or miss header, so you can check what happened.
• Cached files are in application/data/cache/. describe says whether the cache is on (site.page_cache).

Settings:

config::set('page_cache')->to(true);            // force on (or false: force off), whatever the environment
config::set('page_cache_ttl')->to(600);         // seconds a copy stays fresh (default 3600)
config::set('page_cache_skip')->to(array('lab', 'shop/cart'));   // path patterns never cached

Use page_cache_skip for pages that must be fresh on every visit (a random quote, a live stock count).

Set with config::set('name')->to(value) in config/the_app.php.

Environment variables win over the settings above. Set them in your server's configuration (PHP-FPM pool, Apache SetEnv, a .env loaded by your process manager, a container definition) or before a command.