> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ontime.hosai.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Install the connector

> Run the OnTime connector near your terminals: prerequisites, configuration, and pointing devices at it.

The connector is a small Docker service that listens for terminal connections on your network and forwards their messages to OnTime over HTTPS.

## Prerequisites

<Steps>
  <Step title="A host on the same network as your terminals">
    Anything that runs Docker: a small server, a NUC, a VM. It does not need to be powerful — the connector holds no state and does almost no work.
  </Step>

  <Step title="Outbound HTTPS to OnTime">
    The host must reach `https://app.ontime.hosai.app`. Nothing needs to reach *in* from the internet.
  </Step>

  <Step title="An inbound TCP port reachable by the terminals">
    Default `7005`. The terminals connect **to** the connector, so this port must be open on the host's local network.
  </Step>

  <Step title="A connector secret">
    A shared secret that authenticates the connector to OnTime. Ask your OnTime contact to provision one.
  </Step>
</Steps>

<Warning>
  **The connector cannot run on Render**, where the rest of OnTime is deployed. Render web services accept only public HTTP(S), and the connector needs a raw TCP listener. Run it on your own network — which is where it belongs anyway, next to the hardware.
</Warning>

## Configuration

Four environment variables:

| Variable           | Default                         | Meaning                                                                              |
| ------------------ | ------------------------------- | ------------------------------------------------------------------------------------ |
| `LOGSERVER_PORT`   | `7005`                          | The TCP port terminals connect to.                                                   |
| `BACKEND_URL`      | `http://localhost:3000`         | Your OnTime backend's base URL. **Set this** — the default is for local development. |
| `CONNECTOR_SECRET` | `dev-insecure-connector-secret` | The bearer secret. **Set this.**                                                     |
| `DEVICE_TZ_OFFSET` | `+05:30`                        | The timezone the terminals report wall-clock time in.                                |

<Warning>
  **Never deploy with the default `CONNECTOR_SECRET`.** It is a development placeholder, its value is published, and it authenticates a service that can write attendance for every organization. Generate a strong random value and set it on both the connector and the OnTime backend — they must match exactly.
</Warning>

## Running it

```bash theme={null}
docker run -d \
  --name ontime-connector \
  --restart unless-stopped \
  -p 7005:7005 \
  -e BACKEND_URL="https://app.ontime.hosai.app" \
  -e CONNECTOR_SECRET="<your secret>" \
  -e DEVICE_TZ_OFFSET="+05:30" \
  ontime-connector
```

The image is built from `connector/Dockerfile` in the OnTime repository as a bundled single-file build.

<Tip>
  `--restart unless-stopped` matters more than it usually does. The connector is stateless, so restarting it is free — and any punch in flight when it dies is simply re-sent by the device.
</Tip>

## Pointing terminals at it

On each terminal, set its **LogServer** configuration:

| Setting         | Value                                               |
| --------------- | --------------------------------------------------- |
| **Server IP**   | The connector host's address on your local network. |
| **Server port** | `7005`, or whatever you set `LOGSERVER_PORT` to.    |

The exact menu path varies by model — look for "LogServer", "Server settings" or "Communication" in the device's admin menu.

Once set, the device opens a persistent connection and starts streaming. It should appear in OnTime's unclaimed-devices list within a minute.

## The timezone assumption

<Warning>
  **F500 terminals report wall-clock time with no timezone.** The connector stamps every message with `DEVICE_TZ_OFFSET`, which defaults to `+05:30` (India).

  If your terminals are set to a different zone, set this to match — otherwise every punch lands at the wrong time, shifting late arrivals, overtime bands and day boundaries.

  **A deployment spanning multiple timezones needs one connector per zone**, each with its own offset. There is no per-device offset.
</Warning>

## Verifying

<Steps>
  <Step title="Check the connector logs">
    You should see connections from your terminals and acknowledgement lines as messages are forwarded.
  </Step>

  <Step title="Check the Devices page">
    Terminals should appear as unclaimed serials, then flip `Online` once registered.
  </Step>

  <Step title="Run the fake device">
    To validate the whole path without waiting for a real punch. See [Test with a fake device](/terminals/test-with-fake-device).
  </Step>
</Steps>

## Common problems

<AccordionGroup>
  <Accordion title="Terminals connect but nothing reaches OnTime" icon="unplug">
    Check `BACKEND_URL` and `CONNECTOR_SECRET`. A wrong secret means OnTime returns `401`, so the connector never acknowledges — and the device correctly keeps retrying. **Nothing is lost**, but nothing arrives either, and the device's queue backs up.
  </Accordion>

  <Accordion title="Terminals cannot connect at all" icon="cable">
    Firewall on the connector host, or the wrong IP on the device. Confirm the port is reachable from a terminal's subnet.
  </Accordion>

  <Accordion title="Punches arrive at the wrong time" icon="clock">
    `DEVICE_TZ_OFFSET` does not match the terminals' configured timezone.
  </Accordion>
</AccordionGroup>

More in [Troubleshooting](/terminals/troubleshooting).