E Erlangly Try it free

Troubleshooting

The usual causes when something doesn't work, and what to do about each. Settings → System, and erlangly status on the server, list anything Erlangly already knows needs looking at, with what to do.

The install stops: a port is in use

Docker says the address or port is already in use, or already allocated: something else on the server answers on port 80 (or 443, with a domain). Often it's a web server that came with the server, or another container.

  1. See what it is: sudo ss -ltnp 'sport = :80' (or :443).
  2. Stop it if you don't need it, like sudo systemctl disable --now apache2. If you do need it, it can be Erlangly's proxy instead: in /etc/erlangly/erlangly.conf (with sudo), put another port in ERLANGLY_HTTP_PORT=, the https:// address people will open in ERLANGLY_URL=, and leave TLS_DOMAIN= empty, as in Behind your own proxy.
  3. Run erlangly restart, then erlangly setup-link for the setup link the install didn't get to print.

HTTPS doesn't work: the certificate

With a domain in TLS_DOMAIN, Erlangly asks Let's Encrypt for a certificate the first time someone opens it. Let's Encrypt checks the domain is yours by reaching the server from the internet, so until it can, browsers can't make a secure connection.

  • The domain points somewhere else, or nowhere yet: dig +short wfm.example.com should print the server's public address. If the domain also has an IPv6 (AAAA) address, it must be this server's too, or be removed.
  • Ports 80 and 443 aren't open to the internet: a cloud firewall or security group, or ufw, has to let both in from anywhere, not only from your office.
  • A proxy or CDN in front, like Cloudflare's: set the name to DNS only, or let that proxy handle HTTPS and run Erlangly behind it instead.

Once it's put right, run erlangly restart and open Erlangly again. Let's Encrypt allows only a few failed tries an hour for a name, so if it has failed several times, wait an hour first.

Behind your own proxy

  • The wallboard doesn't update by itself, or a schedule being generated never says it's done until you reload: the proxy isn't passing on WebSockets, at /cable. Turn them on (Nginx Proxy Manager: Websockets Support). Caddy and Cloudflare tunnels pass them on as they are.
  • Signing in fails with “The change you wanted was rejected”, and live updates don't come (erlangly logs says Request origin not allowed): the proxy changes the Host header to Erlangly's own address, or ERLANGLY_URL in /etc/erlangly/erlangly.conf isn't the https:// address people open, so Erlangly thinks they came over plain HTTP. Have the proxy pass on the address people opened, put it in ERLANGLY_URL, and run erlangly restart.
  • Everyone is asked to wait a few minutes when a floor signs in at the start of a shift: Erlangly sees every sign-in coming from the proxy. Have it send X-Forwarded-For, and if it runs on another machine, put its address in TRUSTED_PROXIES (how).
  • An import or an API request is refused as too big by the proxy: nginx takes only 1 MB unless told otherwise, and imports can be 5 MB.

For nginx, with Erlangly installed with ERLANGLY_HTTP_PORT=8095 ERLANGLY_URL=https://wfm.example.com:

location / {
  proxy_pass http://127.0.0.1:8095;
  proxy_set_header Host $http_host;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_http_version 1.1;
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection "upgrade";
  client_max_body_size 10m;
}

An upgrade rolled itself back

erlangly upgrade printed the new version's log, said it didn't start, and rolled back. Nothing is lost: you're on the version you had, with your data as it was before the upgrade, and nobody used the new one in between.

  1. Keep the log lines it printed: they say why the new version didn't start.
  2. Run erlangly status: it shows how much disk is free, and anything else that needs looking at.
  3. Send us the log, with the two version numbers, and try again once we've answered or a newer release is out.

Other times an upgrade stops before it starts, and says why: there isn't room on the disk for the snapshot it takes first (free some, docker system prune removes old images), the server can't reach get.erlangly.com or GitHub's registry (see Network), or, with a pay-once licence, the release came out after your Updates ended. If a rollback can't put your data back, Erlangly stays stopped with its data as it was: free some disk and run erlangly rollback again.

Email isn't sent

Settings → Email shows an email Erlangly couldn't send, who it was for and why (a refusal in the mail server's own words), and Settings → System names the last one for a day. Erlangly tries again by itself for about four hours when the server is busy or can't be reached.

  • It couldn't reach the mail server: check its name and port. Some hosting companies, DigitalOcean among them, block outgoing mail ports on new servers until you ask them to unblock one.
  • It stopped answering, or a secure connection failed: Security has to match the port: STARTTLS for 587, TLS for 465.
  • The sign-in was refused: the username or password is wrong. Microsoft 365 also needs SMTP sign-in turned on for that mailbox, and Gmail needs an app password.
  • The sender was refused: the Send from address under Settings → Email has to be one that account may send as.
  • It's sent, but people don't get it: look in their spam folder, and check with your mail provider that the Send from address's domain is set up for it (SPF and DKIM).

The licence key isn't accepted

  • “That isn't a valid Erlangly licence key”: copy the whole key from the email, from ERLANGLY1 to its end, and paste it again. A key that was revoked because it leaked or was shared is refused the same way.
  • It's saved, but the plan still says Free: the key's date has passed. Each yearly renewal emails a new key to whoever bought the licence: paste the newest.
  • Agents can't be added: as many agents as the key covers are already active, sample data included. Schedules can't be generated: there are more active agents than the key covers, or the schedule period has more people than it covers. Settings → Licence shows both numbers.

Still stuck? Write to licences@erlangly.com from the address you bought with. More in Your licence.

An ACD connection has gone quiet

Settings → System says Erlangly can't connect to a connection, or that no agent states have come from it for half an hour while people are on shift. Until they come back, the wallboard and adherence don't know what agents are doing. Open the connection under Settings → Connections: it shows when the last change came, or, when it can't connect, what the ACD answered.

  • The ACD turned the sign-in away: its secret or key was changed, expired or deleted, a permission was taken away, or the user it belongs to was turned off. Choose Change and enter them again; its agents, state codes and queues are kept. Zoom takes an app's admin scopes away when its maker's role changes, and Five9 allows one session per user, so the user made for Erlangly mustn't sign in anywhere else.
  • It can't be reached: check the server can reach the ACD's addresses (see Network).
  • Amazon Connect says it didn't accept the access key or secret, and they're right: check the server's clock, which has to be within 5 minutes of the right time (timedatectl).
  • Another ACD, or a script: the script has stopped, or sends with an old token. The API answers each state it's sent with what it did with it, so the script's log says which.

A connection Erlangly reads from your ACD itself also has a diagnostics file on its page, with people's names and emails masked and nothing secret in it: send it to us if none of these is it.

Locked out

  • An admin's password is lost: erlangly reset-link your@email on the server prints a link to choose a new one, good once, for 15 minutes.
  • Single sign-on is down or set up wrong: break-glass admins sign in with their password. On the server, erlangly sso off stops requiring it.
  • A new install's setup link is lost: erlangly setup-link.

Asking us for help

Write to hello@erlangly.com with what happened and when, and, from the server:

erlangly status
erlangly logs --tail 200

Look through the log before you send it: it can include people's names and email addresses. For an ACD connection, add its diagnostics file.