Skip to content

Setting up a central ECCE server

Jump to bottom
andy edited this page Sep 25, 2026 · 3 revisions

Setting up a central ECCE server

ECCE can run two ways.

Per user (the default). Each user gets their own data server and message broker, started automatically the first time they run ecce. Nothing to configure. Right for a workstation.

Central server. One server holds everyone's calculations and the shared structure and basis-set libraries, and many clients connect to it. This is how ECCE was originally deployed. Use it for a teaching machine with a class on it, or when several workstations should all see the same data.

Both modes work from the same installation. Setting up the second does not take the first away — ecce still runs locally, ecce -remote uses the central server.

Before you start

You need:

  • A machine to be the server, reachable by name from every client.
  • ECCE installed on the server and on each client.
  • Root (or whoever owns /opt/ecce) on each machine, once.

Two ports must be open from the clients to the server:

Port What
8096 data server (Apache/WebDAV)
8095 message broker (ActiveMQ)

Part 1 — the server

On the server machine.

1. Start the services

ecce-dataserver-start
ecce-gateway-start

Check they came up:

ecce-dataserver-status
ecce-gateway-status

2. Create an account for each user

Every user needs an account on the server, whichever machine they sit at:

ecce-dataserver-adduser alice
ecce-dataserver-adduser bob

It will prompt for a password for each. These are ECCE accounts, not Unix accounts — they have nothing to do with the user's login.

3. Check it is reachable from elsewhere

From a client machine:

curl -I http://SERVER:8096/Ecce

Anything other than a refused connection means the port is open. If it hangs or is refused, it is a firewall — open 8096 and 8095 before going further, because everything below assumes they are open.

Part 2 — each client

On every client machine, once, as root:

ecce-remote-setup SERVER

Replace SERVER with the server's host name. That is the whole configuration step. It:

  • writes /opt/ecce/siteconfig/RemoteServer/ pointing at that host
  • points the message broker at the same host
  • keeps a copy of the original broker settings, so the machine can be put back to local-only later

If your server uses non-default ports:

ecce-remote-setup SERVER 8096 8095

Part 3 — using it

Users run:

ecce -remote

This connects to the central data server and broker and does not start per-user copies of either. Users log in with the ECCE account created in Part 1 step 2.

Plain ecce still runs the per-user local servers, so one installation serves both.

Checking it worked

On a client, ecce -remote, then:

  • The login box should accept the account you created on the server.
  • The Organizer should show the same data from every client.
  • On the client, ecce-dataserver-status should report nothing running locally — if a local data server started, -remote did not take effect.

Create a calculation on one client and confirm it appears on another. That is the real test: it means both are talking to the same server.

If something does not work

The login box never accepts anything. Usually the account does not exist on the server, or the client is pointed at the wrong host. Check /opt/ecce/siteconfig/RemoteServer/DataServers names the server you expect, and that ecce-dataserver-adduser was run on the server.

ECCE starts but nothing loads, or apps fail to open. The broker is not reachable. Check port 8095 from the client, and that java.naming.provider.url in /opt/ecce/siteconfig/jndi.properties names the server. ecce-remote-setup sets this; if the file was edited afterwards it may have been reverted.

A local data server starts anyway. -remote was not seen. Check you are running ecce -remote and not just ecce. Setting ECCE_REMOTE_SERVER=1 in the environment has the same effect.

Going back to local-only. Remove /opt/ecce/siteconfig/RemoteServer/, and restore the broker settings from /opt/ecce/siteconfig/jndi.properties.local, which ecce-remote-setup left there for exactly this.

A note on security

The data server authenticates with HTTP Basic over plain HTTP. Passwords cross the network base64-encoded, which is not encryption — anyone able to watch the traffic between client and server can read them.

On a trusted internal network that is the trade-off ECCE has always made. Across anything untrusted, put it behind a TLS reverse proxy or a VPN. Do not expose the server to the open internet as it stands.

Clone this wiki locally