Run one Pipedash server and connect the web, desktop and mobile apps to it. Covers the hosts, pairing a device step by step, address rules, device management and common errors.
In server mode, one Pipedash Server makes every call to the CI/CD providers. The Pipedash Clients on the web, the desktop and the phone show what the server finds. A client needs no provider tokens of its own.
How it works
- Checks: the server polls each provider on its own refresh interval and keeps the results in its database. The Refresh page covers the schedule.
- Live updates: each change reaches every open client at once. A client never polls the providers.
- Actions: a trigger, rerun, cancel or approval goes from the client to the server, and the server calls the provider.
- Tokens: provider tokens stay on the server. A paired device gets only its own device token.
Hosts and clients
| Role | Runs on | How it connects |
|---|---|---|
| Server | A pipedash-web instance, usually in Docker | Serves the web app and the API on one port |
| Server | A desktop app with "Share on this network" on | Serves on its LAN address over plain http |
| Client | A browser | Opens the server address and signs in with the vault password |
| Client | The iPhone, iPad or Android app | Pairs with a code, then keeps one connection to the server |
| Client | The desktop app | Pairs with a code from Settings, Devices, "Connect to a server" |
A phone never acts as a server.
Pair a device
The steps use a pipedash-web server and an iPhone. Android and the desktop app follow the same steps.
Start the server
Run pipedash-web and finish the setup wizard. The Docker page has the Compose files. Behind a reverse proxy, the Reverse proxy page covers TLS and the WebSocket path.
Open the web app at the address the phone will use, such as https://pipedash.example.com. The pairing code carries the address of the open browser tab.
Open Settings, Devices
Settings, Devices holds 2 cards on a server:
- Push alerts: the card "Push alerts for iPhone and iPad" with the switch "Send push alerts through relay.pipedash.app". It is off by default. The Docker page covers it.
- Paired devices: the devices that show the pipelines of this server. It starts empty.
Create a pairing code
Choose "Add device". The dialog shows these items:
| Item | What it holds |
|---|---|
| QR code | The pairing link, for the phone camera |
| Server address | The address of this server |
| Pairing code | 8 characters, such as K7M2-Q9XA |
| Pairing link | A link that starts with pipedash://pair, with a copy button |
| Countdown | "Code expires in 5:00" |
A code works once and expires after 5 minutes. The server keeps at most 8 open codes. Leave the dialog open while the phone connects.
Choose Connect to a server on the phone
On the first start the app asks "Where should Pipedash run?". Choose "Connect to a server". "On this device" makes the phone poll the providers itself.
An existing install skips the question. Open Settings, Devices on the phone and choose "Connect to a server" there.
Scan or type the code
Use one of these ways:
- Tap "Scan pairing code" and scan the QR code. The app asks for camera access the first time.
- Scan the QR code with the system camera. The link opens in Pipedash.
- Paste the pairing link into "Server address". The code field disappears.
- Type the server address and the pairing code.
Tap "Connect" to finish. On iOS, the first connection to a host on the local network also asks for Local Network access.
Check the connection
The phone shows "Connected to pipedash.example.com" and the "Open dashboard" button. The dashboard then shows the pipelines of the server.
At the same time the dialog on the server changes to "Ana's iPhone is connected." with a "Done" button. The name comes from the device.
Manage devices
Settings, Devices on the server lists each paired device with its platform, paired date and last connection. "Push alerts on" marks a phone that gets push alerts. The trash button removes a device after a confirmation. The server closes its connection at once, and the device shows "This device was removed".
On a paired phone, Settings, Devices shows "Shows pipelines from pipedash.example.com." and a "Disconnect" button. Disconnect tells the server to forget the phone. The phone marks its own row with "This device".
A factory reset on the server removes every paired device.
Share a desktop app
A desktop app can act as the server for phones and other computers on the same network.
- Open Settings, Devices and turn on "Share on this network". The firewall can ask whether Pipedash may accept incoming connections. Allow it.
- Choose "Add device" and follow the same steps as above.
The desktop app serves at http://<lan-ip>:<port> and shows the address next to "Sharing at". Keep the computer awake and Pipedash open. A new LAN address needs a new pairing. "Use a new port" changes the port, and every device must pair again. The Desktop app page covers the details.
Address rules
httpsaddresses always work.- Plain
httpworks only for a private network address, and only after "Allow unencrypted connections on private networks" is on in the app. The switch is off by default. Anyone on that network could read the pipelines and the access token of the device. - A plain
httpaddress on the public internet is always refused.
The Security page lists the private address ranges.
What a paired device can change
A paired device uses the providers, views and settings of the server. It cannot change the vault, setup, storage, push settings or factory reset of the server. The server answers 409 with HOST_MANAGED. A device can still remove itself and manage its own push registration.
Alerts
The server records an alert when a pipeline fails or turns degraded, or when a run takes much longer than usual. A provider outage or recovery also raises one. The server records alerts only while at least one device is paired. Phones check for alerts in the background. With the push relay on, iPhone and iPad also get push alerts. The relay receives only an alert id, and the phone downloads the alert text from the server. The Notifications page covers the details.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| "Other devices can't reach this address" in the Add device dialog | The browser opened the server at localhost or another loopback address | Open the web app at its network address, or type that address on the phone |
| "This code expired." | 5 minutes passed | Choose "Create new code" |
| "This server doesn't use encryption" | The address uses plain http | Turn on "Allow unencrypted connections on private networks" for a trusted private network, or serve the server over https |
| "Couldn't connect" | The address or the code is wrong, or the code was already used | Check both and try again with a new code |
| "This device was removed" | The server removed the device | Choose "Set up again" and pair with a new code |
| The phone stops updating from a desktop | The desktop app closed, slept or changed its LAN address | Open Pipedash on the desktop. After an address change, pair again |