Connect to a server — Commentware

Get a connection string, open it in Chrome, and hold several servers in one browser.

Connect the extension to a server with a connection string — the first time, after a new key, or to add a second server — and hold more than one server in a browser. The extension talks to exactly one server at a time, and a connection string — one link that carries the server’s address and your access key — is how it is told which.

Prerequisites

The extension installed. See Install the Chrome extension.
A Commentware server to connect to: your own, from Install a server, or one somebody else runs.

Get a connection string

If somebody else runs your server, ask them for a connection string. It is one link, and it is yours alone.
If you run the server, mint one yourself. See mint a connection string below.

Open a connection string

Open the connection string in Chrome. It lands on /ext/auth/ on this site.
In the small window the extension opens, select Connect — or Add server for a second one, or Replace key for a server you already hold. Nothing connects without that press, and the tab you opened closes itself.

What a connection string holds

A connection string looks like this:

https://<this site>/ext/auth/#?server=<your server>&accessKey=<key>

The # is the point of the format. Everything after a fragment marker stays in your browser: it is not in the request line, not in this site’s access log, not in a proxy’s log, and not in the Referer header when the page links onward. A key in a query string would be in all four.

That also means this site never receives your key or your server’s address, even though the link is addressed to it. The page you land on is served by this site; the part that matters is read by the extension, in your browser.

Mint a connection string

For the person who runs the server:

Mint one for a user, as Manage users and access keys shows. On a new server, commentware users generate 1 mints admin’s.
If your browser reaches the server through a forwarded port, a tunnel or a proxy, mint it with the port you reach it on. See an address your browser can reach.

An address your browser can reach

The string names the address the server actually bound, read from the running server itself. That is right when the browser and the server are on one machine, and wrong when they are not — a 127.0.0.1 address means the browser’s own machine, not the server’s.

For a server behind a forwarded port, a tunnel or nginx, mint the string with the port you reach it on:
```
commentware users new alex --port 8443
```

If nothing is running when you ask, the command falls back to the port a commentware.config.json names, and then to the shipped 7042 — and it tells you when it has had to guess.

Hold several servers

To add a server or switch to another:

Open the extension’s options page: the gear in the side panel’s header.
Under Connection, add a server by its address — it needs no key to be added — or select the one to make current.

A browser holds a list of servers with one current — a work server and a personal one, say — and switching between them is a click on the options page rather than a re-paste. The extension’s options page, under Connection, is where that list lives.

A link adds a server. It becomes the one your comments go to only when it is the first one. Following a link to a second server does not move your writing to it — the options page’s list is where you switch, and the screen the link opens says which of the two it is about to do.
Pasting a string for a server already on the list asks before it replaces your key. Regenerating a key is the ordinary reason to paste a second time, and it still works — but the key that goes is yours, so it is a button that says Replace key rather than something that happens quietly under a button that says Connect. A string for a server you already hold with a key you already have does nothing at all.
A server can be added by address with no key at all. Discovery needs no key, so “is that server running, and what does it speak” is a question you can ask before you have credentials for it.
A server on your list is also an address comment links open on. A server serves its own copy of the page a permalink lands on, so a link built on that server’s own address opens in this browser directly instead of going through this site to name a server this site never sees. Learn more about links to a comment. It is only ever that server’s own links, and it lasts exactly as long as the server is on your list — press Forget on the row and it ends with it. Forget key does not end it: that one keeps the server and drops only the key.
Each entry remembers which project this browser is working in on that server. Learn more about projects, sites and pages.

You will be offered a switch rather than switched. Start commenting on a site that a different connected server already holds comments for, and Commentware says so and names that server — its address as well as its name, because every server is called “Commentware” until somebody renames it. It never switches on its own: that would change what every open surface is showing while you are reading one of them.

Check that it worked

The extension’s options page, under Connection, lists the server as current, with the key’s user and what it may do.

Next steps

Comment on a page: leave your first comment on the server you connected.