Add a second application to an organization

An organization can hold more than one application. Each one answers under its own first path segment, and one login reaches all of them.

Read An organization, its applications and one login before you split an application in two. It says what the applications of one organization share, and when to use two organizations instead.

1. Give each application a mount

An application with no mount: is served under its own name. Declare one when you want a shorter or a different address:

app city_news "Sampletown News" {
  mount: news
}

Its pages are then served under /news/. See App mount for the value and its refusals.

2. Install it into the organization that exists

matterdata install adds the application when the tenant file is already there. The command is the same one that creates an organization:

matterdata install \
  -dir .local/tenants \
  -tenant sampletown \
  -app path/to/city-news

It prints the mount it installed at:

added city_news to .local/tenants/sampletown.db at /news

The command creates the new application’s tables and one new active model row. It changes nothing that is already in the file.

A role belongs to one application. A login that has a role in the club application holds no role in the newspaper application until you grant one.

Pass -email and -role together:

matterdata install \
  -dir .local/tenants \
  -tenant sampletown \
  -app path/to/city-news \
  -email board@sampletown.example \
  -role editor

board@sampletown.example is now "editor" in city_news
added city_news to .local/tenants/sampletown.db at /news

The address must already be a login of this organization. Adding an application never creates one. To create a login, use the administration page — see Manage logins for your organization.

A login with no role in the new application can still sign in. In that application it is anonymous, so it opens the pages a visitor with no session can open, and nothing else.

4. Check how people reach each application

Open the organization’s own root, https://sampletown.matterdata.example/. It lists the applications this person can open and names the role they hold in each.

Two cases differ:

An organization with one application redirects / into it.
An application that declares mount: / answers / itself, and no list is drawn.

There is no switcher in the page frame yet. A person moves between applications through / or through a bookmark. Project status tracks this.

What install refuses

Every refusal happens before anything is written, and each message names the repair.

You ran	What happens
`install` for an application already in this organization	refused. Changing an installed application is `deploy`, which is not built
`-app` for a second application at a mount another one has	refused, naming both applications
`-app` for a second application declaring `mount: /`	refused. An organization has one root application
`-app` for an application whose mount is a page of the root application	refused, naming the page it would hide
`-role` with a role the new application does not declare	refused, listing the roles it does declare
`-email` without `-role`, or `-role` without `-email`	refused. They name a login and what it becomes
`-password`, `-demo`, `-reset-nightly` or `-profile`	refused. Each describes creating an organization, not adding an application to one

The mount collisions are checked by the same code the engine runs when it opens the organization. A refused installation therefore cannot leave an organization that no longer serves.

Changing an application that is already installed

install only ever adds. A new column, a new page or a renamed table needs matterdata deploy, which holds the destructive-change guard and the rollback that install does not. deploy is not built. See Project status.