Fediversity Panel

User guide

This guide helps deploy and manage Fediversity applications. It uses core's concepts.

Log in

Open the panel and click the login link. If your hosting provider has single sign-on, use "Log in with ..." and log in with your hosting provider account. Otherwise, use the local account that your hosting provider gave you.

The "Start" page shows the steps below:

Make a deployment

A deployment is one set of applications under one domain.

  1. Go to "Deployments", and click "New deployment".

  2. Give the deployment a name.

  3. Fill in the settings. Make sure to set:

    • the email address of the administrator. Your deployment sends the password-reset link of its administrator account to this address (see Set your administrator password).
    • the domain. Your applications use subdomains of it. Make sure that the domain is available, for example with an ICANN lookup. The deployment registers the domain for you.
    • the applications that you want, with "enable".

  4. Option click "Validate" to find errors in the form before you deploy. Click "Save" to keep your changes without a deploy.

The operator configuration page tells what each setting does.

To change the settings of one application only, click its settings link on the "Instances" page. This form shows a part of the same deployment:

Deploy

  1. Click "Deploy". The panel saves the configuration and starts the deploy.
  2. Wait. The state of the deployment changes from building to deploying, and then to active. The "Deployments" page shows the state and the time of the last build.
  3. If the deploy fails, the panel shows the end of the log of the build. Correct the cause, and click "Deploy" again.

The first deploy of a new domain takes the longest, because it can register the domain and gets its TLS certificates.

The "History" table on the page of a deployment shows the last deploys, cancels and deletes of the deployment: when, by which account, and if the panel accepted or refused the action.

Open your applications

Go to "Instances". Each deployment shows a card for each application, with a link to the site of the application. The changed tag tells that the saved configuration of the application is different from the deployed one: deploy again to apply it.

Set your administrator password

Each deployment has its own single sign-on (SSO), with Authelia at auth.<your domain>. Its administrator account has the user name operator and starts without a password:

  1. Open https://users.<your domain>/reset-password/step1.
  2. Enter operator.
  3. Open the link in the email that the deployment sent to the address you set.
  4. Set a password.

Use the same page to reset this password later. The "Reset password?" link at auth.<your domain> does not work for this account, because the account can manage users in lldap.

After this, log in to your applications with their SSO or OpenID Connect (OIDC) login option. The same account works in all of them.

Manage the users of your deployment

The users of your deployment are in its lldap directory, at https://users.<your domain>/. Log in there as operator. You can add users there, e.g. for when your applications do not allow public sign-up.

The groups that are important:

Group What a member can do
authelia-users Log in through SSO to the applications of the deployment. Add each new user to this group.
fediversity-admins Use the administration tools of the deployment. Give this group only to people who administer it.
lldap_admin Manage users and groups in lldap.

A new user sets a password with "Reset password?" at auth.<your domain>. A member of lldap_admin sets a password the same way as operator.

Change or remove a deployment

  • To change a deployment, click "Edit" on the "Deployments" page, change the settings, and click "Deploy".
  • To start from a copy of a deployment, click "Duplicate". Change the domain of the copy before you deploy it.
  • To remove a deployment and all of its applications and data, click "Delete", and confirm. You cannot undo this. The registration of its domain stays with your hosting provider.

Send requests to the API

The panel uses the API of your hosting provider. You can also send requests to this API yourself, for example from its Swagger UI page. Your hosting provider links this page from its overview page, and the panel links it from your account page.

  1. Click your user name to open your account page.
  2. Under "API access", click "Copy API token". The panel copies a token to the clipboard, and shows it in a field below the button. If the clipboard is not available, copy the token from that field.
  3. In the Swagger UI, click "Authorize", paste the token and click "Authorize" again.

The API then lets you do what the panel lets you do. The token expires after a few minutes. The account page shows when. When the token expires, the API answers 403. Then copy a new token and replace the old one under "Authorize".