Using modules
This page is for a site’s owner: how to manage the modules a site has, and how to add one that lives outside the engine. For what the modules are, see the overview.
The Modules page
Section titled “The Modules page”Open Modules in the admin toolbar (/admin/config/modules). It lists
every module the site’s binary has, by category - Content, Media,
Community, Administration, Integrations, then Other for the
modules without one - each with a switch to enable it and a short
description. The categories are folded, each line naming its modules
that are on; click one to open it, or Expand all. The links at the top
open a category and say how many of its modules are on. A module that
isn’t installed (never was, or was uninstalled) is marked Not
installed, one from its own repository from its own repository; a
disabled, installed one has an Uninstall link.
Under each module, What the module includes lists what it owns on this site: the modules it requires and those that require it, its content types and how many items each has, where its blocks are placed, its permissions and how many roles have them, its admin pages, how many rows its data tables have, and its CSS and JavaScript files.
Enable a module
Section titled “Enable a module”- Tick the module and click Save.
- The first time, the module installs itself: its tables are created, its install step writes its starter data (for example, the image styles of Galleries), and its blocks that name a region are placed in the site’s theme. Labels it writes are put in the site’s language. If the install fails, nothing is saved.
- Give roles the module’s permissions, if it has any (Users → Permissions), and place its blocks (Structure → Blocks, see Blocks).
A module can require others. It can only be enabled together with them, and they can’t be disabled while it is on: the page refuses and saves nothing.
Disable a module
Section titled “Disable a module”Untick it and save. While it is off:
- its pages answer 404 (pages with the site’s 404 page,
/api/*addresses with a JSON error); - its admin pages, its links on pages and its items in the Create content menu are hidden, and its CSS and JavaScript are not loaded;
- its blocks are not offered for placement, and placed ones are not shown;
- its permissions are hidden from the permissions page (the roles keep them);
- content of its types doesn’t open and can’t be created, edited, deleted or commented on; it isn’t in the sitemap or search;
- its sort criteria, filters and fields in Views are skipped;
- its processing in the text formats (Processing when shown) and its choices in a field’s How to show are off: texts and fields show as they would without it.
The data stays: enabling the module again brings everything back. Disabling doesn’t edit your Views: one that lists content of the module’s type still lists it (the items don’t open), so edit the View yourself.
Choose the modules of a new site
Section titled “Choose the modules of a new site”app install installs the standard modules (Forms, Private messages,
Subscriptions, Video embeds, Action log and 404 log;
with -demo-set, also those the set has content for) unless -modules
says otherwise:
app install -site-name "Example" -admin-name admin -admin-email admin@example.com \ -modules polls,forms,error_reports,private_messages,subscriptions-modules takes machine names separated by commas, all or none.
A module the listed ones require is added. The others are recorded as
disabled and not installed: their tables don’t exist and app migrate
skips them until you enable them on the Modules page. With -demo, each
installed module adds its own demo content. See
app install.
Uninstall a module
Section titled “Uninstall a module”Uninstalling removes a module’s data for good. Back up the database and the files first (see Backups in Running in production).
- Disable the module and save.
- Click Uninstall next to it. When a module can’t be uninstalled, the reason is shown instead: another installed module requires it (uninstall that one first), or it keeps data in the core’s tables and has no uninstall step for them.
- The page lists everything that will be deleted. Read it.
- If the module has content, delete it first: type the module’s machine name and click Delete the content. Each item is deleted with its comments, field values and the files nothing else uses. A large site takes several runs; the page says when some are left.
- Type the machine name (again, if you deleted content) and click Uninstall.
This removes the module’s block placements, the menu links to its pages, its permissions and its content types’ permissions in roles, the search, SEO, breadcrumb and block visibility settings of its content types, its sort criteria, filters and fields in Views, the texts of its emails changed on the Mail page, its processing in the text formats, its choices in the fields’ How to show (those fields show as the core shows them), whatever its own uninstall step removes, its tables, its records of applied migrations and the files only its tables used. The module stays on the Modules page, disabled; enabling it again installs it from scratch. If something fails halfway, run the uninstall again: each step can be repeated.
Updates
Section titled “Updates”A module’s database changes come with the binary, like the core’s. After
deploying a new binary, run app migrate (the plan) and
app migrate -apply. It covers the core and every module that is
enabled or installed; an enabled module that isn’t installed yet is
installed. See
app migrate.
Add a module from its own repository
Section titled “Add a module from its own repository”A module from outside the engine is a Go module. To use it, the site
builds its own binary: the engine plus the modules it imports. The
repository’s
examples/hello-site
is such a site, with the example module
examples/hello.
You need Go (the version in the engine’s go.mod) on the machine that
builds the binary.
-
Create the site’s main package, once. In an empty directory:
Terminal window go mod init example.com/my-siteand a
main.go:package mainimport "github.com/kosatka-cms/kosatka"func main() { kosatka.Main() }Then fetch the engine:
Terminal window go mod tidyThis binary is the whole engine: it has every command of
app(install,migrate,module,assets…). -
Add the module by its Go package path, with a version or without one (the latest):
Terminal window go run . module add example.com/kosatka-hello@v1.2.0It runs
go getand writeskosatka_modules.go, a file that imports the module:// Code generated by "app module"; DO NOT EDIT.// The modules from outside the engine this site has: each registers// itself when imported (modulekit.Register).package mainimport (_ "example.com/kosatka-hello")Don’t edit it by hand;
app module addandapp module removekeep it. Ifgo getfails, the file is left as it was. Both commands work only in a site’s own main package: in the engine’s repository they refuse, since its modules are built in. -
Check the binary has it:
Terminal window go run . module listIt prints the engine’s modules and then each module from outside it with its Go package and version.
-
Build the binary, for example for a Linux server:
Terminal window CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o kosatka .Like the engine’s own binary, it runs from a directory with the engine’s
web/andthemes/: take them from the engine’s repository at the release yourgo.modrequires. -
Deploy it as in Running in production, with your binary in place of the engine’s. A module’s templates and static files are inside the binary; if nginx serves
/static/, export them with your binary when you assemble the static files:Terminal window ./kosatka assets export "$stage"(see
app assets). -
On a site that already exists, a module new to the binary is on at once, unless its manifest sets
OffByDefault:app migrate -apply(step 5) installs it. A module withOffByDefaultstays off until you enable it on the Modules page. A new site installs it when its manifest setsInstallByDefault; otherwise list it with the standard ones:-modules action_log,forms,not_found_log,private_messages,subscriptions,video_embed,hello.
To update a module, run go run . module add <path>@<new version>,
rebuild, deploy, and run app migrate -apply.
Remove a module from the binary
Section titled “Remove a module from the binary”-
Uninstall it on the Modules page first (see Uninstall a module).
-
Remove it, with the site’s config so the command can check the site’s database:
Terminal window CONFIG_PATH=/path/to/config.yaml go run . module remove example.com/kosatka-helloThis drops the import from
kosatka_modules.goand the requirement fromgo.mod(go get …@none). While the module is still installed in the site’s database, the command refuses and changes nothing. When it can’t reach the database (no config on the build machine, say), it warns and removes the module: make sure you uninstalled it.-forceremoves an installed module anyway. -
Rebuild and deploy the binary.
With several sites on one engine (see
Several sites on one server), uninstall it on
each site first: app module remove checks the one database its config
names.
A module installed in the database but not in the binary
Section titled “A module installed in the database but not in the binary”A binary built without a module the database has installed (it was removed without being uninstalled, or the site runs an older or other build) still serves the site, but:
- content of the module’s types answers 404, and it leaves the sitemap, the search and the latest comments;
- the module’s pages, blocks and admin pages are gone; menu links to its pages lead to 404;
- its sort criteria, filters and fields in Views are skipped, so a View built on them lists other content;
- it isn’t on the Modules page, so it can’t be uninstalled from there.
Its tables and data stay. The status report shows the warning Modules
missing from the binary, the site logs it when it starts
(level=WARN, with module=<name>), and app migrate prints
<name>: installed in the database, not in this binary. To clean up,
deploy a binary that has the module again, at the version the database
has: the module comes back as it was. Disable it and uninstall it on the
Modules page, then remove it from the binary.