Skip to the page

Connecting a self-hosted Jelly

If you run your own Jelly, you can connect it to the services we run for the teams we host. This page is for whoever looks after the server, because some of the steps change its settings.

Jelly's services run from a server we call the manager. Once your Jelly is connected to it, your team can:

  • write to Jelly's support from the Support page, and let support in with a switch on the request;
  • report a problem with a message;
  • connect Google accounts, and sign in with Google, where we've turned that on for you;
  • use the shared Slack, Discord, iPhone and Mac notification services;
  • have a sandbox team to build against, which Jelly hosts, where we've turned that on for you.

Your team's mail and data stay on your server. A connected Jelly may also have billing, if we set it up for your instance. Until we do, it isn't billed.

Before you start

  1. Settle your server's address. Set the public address your team will always use (JAM_ORIGIN in the server's environment) before you connect. Changing it later can stop passkeys working and break links already sent to your team.
  2. Get a one-time key. Contact the Jelly team and ask us to register that address. We'll give you the manager's address and a one-time key.

Connecting

  1. Sign in as an Admin or the Owner, and go to Settings → Housekeeping.
  2. Under Manager connection, type the Manager URL and the One-time key we gave you.
  3. Press Connect.
  4. In your server's environment, set JAM_MANAGER_URL to the same manager URL.
  5. Restart your Jelly. The connection works from then on.

If you have a shell on the server, you can do steps 1 to 3 from there instead, then carry on with steps 4 and 5:

jam connect <manager-url> <key>

If your database isn't jam.db in the folder you run the command from, add --db and the database's path before the URL. jam disconnect takes the same --db.

Checking it worked

Open Support in the account menu. A connected Jelly shows a form for writing to support, with a switch labelled Allow support to access our data. One that isn't connected shows Support access instead, with a code to send to support.

If connecting fails

Jelly says What to do
the manager URL must be a bare origin Type only the start of the address, such as https://example.com, with nothing after it.
the manager URL must use HTTPS Use the https:// address.
the manager could not be reached Check the address, and that your server can reach the internet.
the manager refused this origin and key The key is wrong or already used, or we registered a different address for your server. Ask us for a new key.
the manager registered a different origin, or sent an invalid answer Check that the server's JAM_ORIGIN matches the address you asked us to register.
this instance's environment already names a different manager JAM_MANAGER_URL is already set to another address. Change it, or connect to that one.

After connecting

Any Google accounts your team connected before now need connecting again. Go to Settings → Connections → Gmail, open each account, and press Reconnect with Google.

If we haven't turned on Google connections for your instance, the Gmail page says Google accounts cannot be connected on this instance. Your team can still send and receive through IMAP and SMTP.

Google sign-in

Once you're connected, and where we've turned Google on for you, your team can sign in with Continue with Google through Jelly's services. There's nothing to set on the server for it. If the server's environment still has GOOGLE_CLIENT_ID or JAM_GOOGLE_HD from before you connected, remove them: a connected Jelly ignores both, and says so in its log.

Google sign-in only ever lets in people who are already members of your team. It's on to start with, and an Admin or the Owner can change it in Settings → Housekeeping, under Google sign-in:

  • Google sign-in turns it on or off. When it's off, the sign-in page has no Google button.
  • Workspace domain, if you fill it in, lets in only Google accounts from that Google Workspace domain, such as example.com. Leave it empty to let in any Google account.

If the manager's Google client changes

The first time your Jelly hears from the manager, it stores the Google client the manager signs people in with. From then on it accepts Google sign-ins only from that client.

If the manager names a different client later, Housekeeping says The manager's Google client has changed. Press Review the change, and accept the new client only if we told you it was changing. Until you accept, Jelly goes on checking every Google sign-in against the stored client, so Google sign-in doesn't work while the manager uses the new one. Emailed links and passkeys still work. If you aren't sure, write to support.

Disconnecting

  1. While you're still connected, write to support and ask us to remove your instance's registration and cancel its key.
  2. On Settings → Housekeeping, press Disconnect. Or, on the server, run jam disconnect.
  3. Remove JAM_MANAGER_URL from your server's environment.
  4. Restart your Jelly.

Disconnecting doesn't move or delete any of your team's data.

Back to the beginning