Custom nodes

A node is a machine you run that hosts identities instead of Joinpane cloud. Websites see your node's own internet line, and the sessions stay on your machine.

When to use one

A website should see your own line: your office, your home, or a place Joinpane cloud doesn't offer.
Sessions must stay on hardware you own. A node keeps its identities' sessions on its own disk.

Windows, Drive, agents, policies and the audit log work the same on a node as in Joinpane cloud. What changes is where the browser runs and the address websites see.

What a node needs

Docker: Any machine that runs Docker: a Linux box, a Mac or a NAS.
Memory: 4 GB or more. Plan on about 1.5 GB for each identity running at once; the node works out how many it holds from its memory, and its page shows how full it is.
Disk: Room for the browser profile of each identity it hosts. Profiles live in the joinpane-node volume, so they outlast the container.
Network: Outgoing HTTPS to joinpane.com, and to the websites its identities use. Nothing comes in, so there's no port to open, and it works behind a home router.
An admin: Admins add and remove nodes and move identities onto them. Everyone in the workspace can see them in Settings.

Add a node

Name it. In Settings, open Nodes and choose Add node. Give it a name people will recognise, like tokyo-office.
Run the command it shows, on the machine, within the hour.
```
docker run -d --restart unless-stopped --name joinpane-node \
  -v joinpane-node:/data \
  -e JOINPANE_TOKEN=jpn_… \
  joinpane/node:latest
```
Starts the node in the background, and again whenever the machine or Docker restarts. The token in it works for an hour.
It calls in. The node appears in Nodes by itself, with the address it called in from. Move identities onto it from its page.

The token works onceAt its first start the node swaps the token for a key of its own, which it keeps in its volume, so the command is no use to anyone afterwards. If the hour runs out first, choose Show a new command on the node; the old token stops working.

What websites see

An identity on a node goes out through the node's own internet line, so websites see the address the node calls in from. The node's page shows it. The browser itself doesn't change: the same device, screen size and settings it always had, so only the address is new.

That's why identities never move between a node and Joinpane cloud by themselves. Moving one is an admin's choice, and the app says what will change first.

Move an identity onto a node

Open the node from Settings, find the identity under Move an identity here, and choose Move here.

The website sees a new address, the node's. It may ask the phone owners for a sign-in code, so move it when they're around.
Its sign-in comes along. The session moves with it, and nobody signs in again because of the move.
Open windows close while it moves, and open again in a moment.
Its IP is released. On the node it uses the node's line. Moving it back means picking an IP again.

An identity waiting for a sign-in code, or still being added, moves once someone has finished signing in.

Move it back to Joinpane cloud

On the node's page, choose Move to Joinpane cloud for the identity and pick an IP for it, the way you would for a new identity.

An online node hands the session over. It seals the session for the identity's next machine and deletes its own copy. The identity wakes in Joinpane cloud, still signed in.
An offline node can't hand it over. The identity still moves, but its session stays behind, and the node deletes it when it next calls in. The identity starts as Not signed in, and someone signs in again in their own window.

When a node goes offline

Its identities pause. People see that the node is offline, and can open them again once it's back, with their tabs.
Nothing moves to Joinpane cloud by itself, so websites never see a surprise address.
Admins get an Inbox note. Starting the container again brings the node back.

Restart a node

docker restart joinpane-node

Restarts the node. Its identities' sessions stay on its disk.

The node's page has the same command under Copy restart command. While it restarts, the node shows as offline and its identities pause; people carry on once it's back.

Keep the joinpane-node volumeThe node's key and its identities' sessions live in the joinpane-node volume. A new container started with the same command and volume carries on where the old one stopped. Without the volume, each identity needs someone to sign in again, and the node needs a new command.

Remove a node

Move its identities to Joinpane cloud. A node that hosts identities can't be removed.
Remove the node. Choose Remove node on its page. Its key stops working. If it's online, it stops its browsers, deletes the profiles and the key it held, and exits.

Remove the container and its volume from the machine.

docker rm -f joinpane-node && docker volume rm joinpane-node

Left in place, the container tries to start again about once a minute, and its log says the token was refused.

What a node holds

Sessions stay on the node. A node keeps its identities' sessions on its own disk, and Joinpane keeps no copy. Only while an identity moves on or off does its session travel, sealed with that identity's key, and the copy in transit is deleted once it arrives.
A node trusts whoever runs its machine. Anyone with administrator access to it can get around a window's lockdowns and read the sessions it holds. Run nodes on machines you control.
It only calls out, over HTTPS to joinpane.com. People's windows reach it through that connection, so nothing on your network is open to the internet.
Windows on a node won't open private addresses, like localhost or 192.168.1.20.

More on how sessions are kept is in Security.

Troubleshooting

Three commands answer most questions about a node:

# Is it running?
docker ps --filter name=joinpane-node

# What is it saying?
docker logs --tail 50 joinpane-node

# Restart it
docker restart joinpane-node

It doesn't appear in Nodes: Check the container is running and read its log, with the commands above. The machine needs outgoing HTTPS to joinpane.com. If the hour ran out before it called in, choose Show a new command on the node, remove the old container with docker rm -f joinpane-node && docker volume rm joinpane-node, and run the new command.
The log says Joinpane refused this node's token: The node was removed, its command was replaced before it called in, or it was started again without its joinpane-node volume (its key lives there). Add it again from Nodes and run the new command.
It shows as offline: Check the machine is on and online and the container is running; docker restart joinpane-node brings it back. Its identities stay paused until it's back.
Windows on it are slow: The node's page shows its processor and memory. Busy or Nearly full means it's running more than it has room for: move an identity to another node or to Joinpane cloud, or give the machine more memory.
The website asked for a sign-in code after a move: It noticed the new address. The identity's phone owners get the code as usual.
An identity on the node is signed out: If the container was removed and started again, its disk started empty. Sign in again in your own window, and the identity is ready for everyone.