Developer guide
Browse by topic
Discover Developer guide
Explore related documentation through its most useful keyword groups.
166 items
Grouped by Domain
Development and debugging
54 itemsBuilding inspecting testing and diagnosing Zotonic applications and modules.
Explore this clusterSite management
34 itemsCreating configuring updating starting and stopping Zotonic sites.
- addsite: Create a site application from a skeleton
- Application startup and per-site module activation
- A site does not start
Configuration
26 itemsDefining site module runtime and service settings.
- A site does not start
- Change a runtime setting deliberately
- config: Display configuration resolved from files
Module management
6 itemsInstalling activating configuring upgrading and removing Zotonic modules.
- A module is discovered but not active
- A module is missing from the admin
- Application startup and per-site module activation
Logging and monitoring
6 itemsRecording and observing events errors state health and performance.
Explore this clusterRouting and redirects
6 itemsMapping incoming URLs to controllers resources or redirect destinations.
- Add your first dynamic page
- A URL reaches the wrong page
- dispatch: Inspect dispatch rules or trace a URL
Media management
5 itemsManaging files and media resources throughout their lifecycle.
- An uploaded image does not display
- Display images with mediaclasses
- Display images with mediaclasses
Content modeling
4 itemsDefining content types properties relationships and constraints.
- Create your first site
- Install initial content with a datamodel
- Model content with categories and predicates
Backup and restore
4 itemsPreserving and recovering site data media and configuration.
- Back up and restore site data
- backup: List, create, or restore backups
- decrypt: Decrypt a local encrypted backup file
Other
43 itemsDocumentation not covered by the other keyword groups in this split.
- Add a database query when models are not enough
- Add a filter or rendering component
- Add an HTTP controller
All Developer guide
pot: Generate gettext translation template files
Generate gettext translation template files.
Prepare local PostgreSQL
Create and check the database used by a native development installation.
Put Zotonic behind nginx
Forward HTTP and WebSocket traffic with a narrow trust boundary.
Read and update resource properties
Use model#rsc for resource access and m_rsc_update for writes. These APIs handle behavior that a direct SQL update would bypass.
Recompile code and refresh discovery
Use compilation for changed Erlang source, loading for changed BEAM files, and an index refresh when new templates or application files are not discovered.
Reload the browser after source changes
Open System → Development and enable live reload. The page also enables separate CSS and JavaScript files when needed.
Render and manage media
Use resource IDs, media metadata and consistent responsive-image descriptors.
resetratelimit: Reset a site rate limiter
Reset a site rate limiter.
Respond to a notification
Find the notification definition and inspect its callers before implementing an observer. The notifier operation determines whether observers collect results
restart: Restart Zotonic and all sites within the current VM
Restart Zotonic and all sites within the current VM.
restartsite: Restart one site
Restart one site.
Reuse markup with includes and categories
Extract repeated markup into a partial and pass its inputs explicitly.
Reuse markup with includes and categories
Extract repeated markup into a partial and pass its inputs explicitly.
rpc: Call an exported Erlang function on the node
Call an exported Erlang function on the node.
Run tests and site checks
Use the project's test workflow in a dedicated development or test environment. Two CLI entry points have different scopes:
runtests: Run selected core test modules
Run selected core test modules.
Runtime data and uploaded files
Keep runtime data separate from the application's source and static assets.
Run work outside a request
Use an existing Zotonic task mechanism when it fits the job. Use a supervised worker when the work needs a persistent process with its own lifecycle.
Run Zotonic as a service
Start a foreground Zotonic process under the host service manager.
Search
Query arguments and terms for searching pages using the search APIs.
Serve HTTPS on a privileged port
Terminate public traffic at a reverse proxy while Zotonic stays unprivileged.
setconfig: Set a global runtime Zotonic value
Set a global runtime Zotonic value.
Set up a local development environment
Choose one installation route, start Zotonic, create a site, and make your first visible change.
shell: Connect an Erlang shell to the running node
Connect an Erlang shell to the running node.
siteconfig: Display a site configuration resolved from files
Display a site configuration resolved from files.
siteconfigfiles: List configuration files selected for a site
List configuration files selected for a site.
Site configuration and enabled modules
A site is identified by its application and priv/zotonic_site configuration. Supported formats include Erlang .config, JSON, and YAML; follow the format…
sitedir: Show a site application directory
Show a site application directory.
sitetest: Run site tests using an isolated test schema
Run site tests using an isolated test schema.
Start in the foreground or background
Choose a startup mode for the environment:
start_nodaemon: Start Zotonic in the foreground without an interactive shell
Start Zotonic in the foreground without an interactive shell.
startsite: Start a selected site on the node
Start a selected site on the node.
start: Start Zotonic in the background
Start Zotonic in the background.
Start, stop, and restart a site
Use these commands for one named site:
status: Show node and site state
Show node and site state.
stopsite: Stop one site
Stop one site.
stop: Stop the Zotonic node
Stop the Zotonic node.
Test Erlang behavior with focused examples
Keep domain logic in small functions that accept explicit inputs. Test expected results, boundary values, and meaningful error cases without starting a full…
Test the database connection
Run bin/zotonic connectdb to test a connection using the global Zotonic database configuration. It does not open PostgreSQL’s interactive client and has no…
Test with different users
Choose roles that exercise the operation's permission boundary: anonymous visitor, limited editor, and administrator. Use separate browser sessions or an…
The Zotonic workspace
The checkout is an Erlang umbrella project: one build contains many applications.
Trace a small number of Erlang calls
Open the Development function tracing tool as the admin user. Enter a module, optionally a function, and a small limit on the number of calls.
Trace a URL through dispatch
Open the Development page's dispatch tools. Inspect the list of active rules, then trace the path that produces an unexpected result.
Trace database queries for your session
Enable module#mod_server_storage if the Development page says it is needed for database tracing. On the Development page, enable Trace all database queries for…
Trace templates rendered by a request
Open the Development page's Live dependency graph of templates tool. Start a trace for your session, then load the page or path you want to inspect.
Trace URL dispatch from the command line
Use dispatch inspection to discover why a path selects a particular controller:
Translate interface text
Write the source text in English and mark static interface text for translation.
Tune server limits from measured load
Check actual limits and workload before changing operating-system settings.
Understand the development workflow
Work in small, verifiable steps: change source, compile or reload, reproduce the request, and inspect the result.
Understand the optional development API
The Development page has an option to enable an API for recompiling and rebuilding Zotonic. The model implements actions for recompiling, flushing caches, and…
update: Compile, load, flush, and rescan the server
Compile, load, flush, and rescan the server.
Update dependencies deliberately
Change a dependency when you can identify the required fix or feature and the affected callers. Read its version constraints and inspect the resulting lockfile…
Upgrade a module's data schema
Version schema changes through the module's installation and upgrade mechanism. Inspect a module using -mod_schema and manage_schema/2 before adding your own…
Upgrade notes
Upgrade notes
Use Cotonic and MQTT for browser messaging
Use the existing Cotonic browser models and Zotonic MQTT bridge when components need to communicate through topics. First identify whether the topic stays…
Use maintainable Zotonic patterns
Start with a working site, reusable templates and the standard media pipeline.
Use stable resource names
A resource has a numeric ID within its database. Give application-owned resources a stable name when code needs to find them across installations.
Use stable resource names
A resource has a numeric ID within its database. Give application-owned resources a stable name when code needs to find them across installations.
Use the Nix development shell
Enter the supplied OTP 28 development shell, prepare PostgreSQL, and build.
Validate a form on both sides
Use semantic form controls with labels and meaningful names. Add Zotonic validators for immediate feedback, then validate the submitted values again at the…
Verify an upgrade before release
Prepare an isolated copy of the previously released application and database. Add representative edited content, then apply the new code and schema changes.
Verify backups by restoring them
Define what must be recovered: database, original media, configuration, and security material. Check which parts the selected backup includes before depending…
wait: Wait until the node answers a ping
Wait until the node answers a ping.
Work with a site context
A context carries the site and request-related state used by Zotonic APIs. Pass it through your functions instead of storing one context globally.
Work with uploaded media
A media resource has ordinary content properties and information about its associated file. Use model#media to inspect and manipulate media through Zotonic's…
Write logs that explain an operation
Log the operation and its result with structured fields. Include an identifier that helps connect the message to a resource or job, without logging credentials…