mirror of
https://github.com/fosrl/docs-v2.git
synced 2026-09-17 19:39:09 +02:00
270 lines
8.8 KiB
Plaintext
270 lines
8.8 KiB
Plaintext
---
|
|
title: "Install Sites"
|
|
description: "Install the site connector as a binary or Docker container"
|
|
---
|
|
|
|
The site connector can be installed as either a static binary executable or a Docker container via the CLI. You must first create a site and copy the ID and secret config from Pangolin before running it.
|
|
|
|
## Binary Installation
|
|
|
|
### Install
|
|
|
|
Use this command to automatically install the CLI. It detects your system architecture automatically and always pulls the latest version, adding the CLI to your PATH:
|
|
|
|
```bash
|
|
curl -fsSL https://static.pangolin.net/get-cli.sh | bash
|
|
```
|
|
|
|
To run a site on Windows, [download the latest installer](https://github.com/fosrl/cli/releases/latest/download/pangolin-cli_windows_installer.msi).
|
|
|
|
Binaries for Linux, macOS, and Windows are available in the [GitHub releases](https://github.com/fosrl/cli/releases/latest) for ARM and AMD64 (x86_64) architectures.
|
|
|
|
### Running the Site
|
|
|
|
Run the site connector with the configuration from Pangolin:
|
|
|
|
```bash
|
|
pangolin up site \
|
|
--id 31frd0uzbjvp721 \
|
|
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
|
|
--endpoint https://app.pangolin.net
|
|
```
|
|
|
|
### Run as a Service
|
|
|
|
The CLI can install and manage a service on your host machine for you. This supports Windows services, MacOS's launchd, and Linux's systemd to create a persistent site connection from that host.
|
|
|
|
```bash
|
|
sudo pangolin service install site \
|
|
--id 31frd0uzbjvp721 \
|
|
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
|
|
--endpoint https://app.pangolin.net
|
|
```
|
|
|
|
Check the service status:
|
|
|
|
```bash
|
|
sudo pangolin service status site
|
|
```
|
|
|
|
And to get the logs:
|
|
|
|
```bash
|
|
sudo pangolin service logs site
|
|
```
|
|
|
|
### Manual Systemd Service
|
|
|
|
Create `/etc/pangolin/pangolin-site.env` with the initial values from your Pangolin site configuration:
|
|
|
|
```bash title="/etc/pangolin/pangolin-site.env"
|
|
SITE_ID=31frd0uzbjvp721
|
|
SITE_SECRET=h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6
|
|
PANGOLIN_ENDPOINT=https://app.pangolin.net
|
|
```
|
|
|
|
Create the directory, write the file, and restrict its permissions:
|
|
|
|
```bash
|
|
sudo install -d -m 0755 /etc/pangolin
|
|
sudo editor /etc/pangolin/pangolin-site.env
|
|
sudo chmod 600 /etc/pangolin/pangolin-site.env
|
|
```
|
|
|
|
Then create a systemd service. The site connector reads those environment variables automatically, so `ExecStart` does not need to repeat them as flags:
|
|
|
|
```ini title="/etc/systemd/system/pangolin-site.service"
|
|
[Unit]
|
|
Description=Pangolin Site
|
|
Wants=network-online.target
|
|
After=network-online.target
|
|
|
|
[Service]
|
|
Type=simple
|
|
User=root
|
|
Group=root
|
|
EnvironmentFile=/etc/pangolin/pangolin-site.env
|
|
ExecStart=/usr/local/bin/pangolin up site
|
|
Restart=always
|
|
RestartSec=2
|
|
UMask=0077
|
|
|
|
PrivateTmp=true
|
|
|
|
[Install]
|
|
WantedBy=multi-user.target
|
|
```
|
|
|
|
<Warning>
|
|
Make sure the binary exists at `/usr/local/bin/pangolin` before daemon reload and starting the service: `~$ which pangolin`
|
|
</Warning>
|
|
|
|
Reload systemd and enable the service:
|
|
|
|
```bash
|
|
sudo systemctl daemon-reload
|
|
sudo systemctl enable --now pangolin-site
|
|
sudo systemctl status pangolin-site
|
|
```
|
|
|
|
If you later change `/etc/pangolin/pangolin-site.env`, restart the service so the site connector picks up the new values.
|
|
|
|
See [Configure Sites](/manage/sites/configure-site) for more environment variables.
|
|
|
|
## Docker Installation
|
|
|
|
### Pull the Image
|
|
|
|
Pull the latest image from Docker Hub:
|
|
|
|
```bash
|
|
docker pull fosrl/pangolin-cli:latest
|
|
```
|
|
|
|
### Run with Docker
|
|
|
|
Run the site connector with CLI arguments from Pangolin:
|
|
|
|
```bash
|
|
docker run -dit --network host fosrl/pangolin-cli up site --id 31frd0uzbjvp721 \
|
|
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
|
|
--endpoint https://app.pangolin.net
|
|
```
|
|
|
|
### Docker Compose
|
|
|
|
#### Environment Variables (Recommended)
|
|
|
|
```yaml title="docker-compose.yml"
|
|
services:
|
|
pangolin-site:
|
|
image: fosrl/pangolin-cli
|
|
container_name: pangolin-site
|
|
restart: unless-stopped
|
|
environment:
|
|
- PANGOLIN_ENDPOINT=https://app.pangolin.net
|
|
- SITE_ID=2ix2t8xk22ubpfy
|
|
- SITE_SECRET=nnisrfsdfc7prqsp9ewo1dvtvci50j5uiqotez00dgap0ii2
|
|
```
|
|
|
|
#### Config File Injected as Compose Secret
|
|
|
|
A safer but slightly more complex way is to use [Compose Secrets](https://docs.docker.com/compose/how-tos/use-secrets/). First, create a `JSON` file containing your configuration:
|
|
|
|
```json title="pangolin-site-config.secret"
|
|
{
|
|
"id": "2ix2t8xk22ubpfy",
|
|
"secret": "nnisrfsdfc7prqsp9ewo1dvtvci50j5uiqotez00dgap0ii2",
|
|
"endpoint": "https://app.pangolin.net",
|
|
}
|
|
```
|
|
|
|
Then register and reference the secret in your `docker-compose.yml`:
|
|
|
|
```yaml title="docker-compose.yml"
|
|
services:
|
|
pangolin-site:
|
|
image: fosrl/pangolin-cli
|
|
container_name: pangolin-site
|
|
restart: unless-stopped
|
|
environment:
|
|
- CONFIG_FILE=/run/secrets/pangolin-site-config
|
|
secrets:
|
|
- pangolin-site-config
|
|
|
|
secrets:
|
|
pangolin-site-config:
|
|
file: ./pangolin-site-config.secret
|
|
```
|
|
|
|
This allows you to separate sensitive secrets from plain configuration, improving security when storing or sharing your `docker-compose.yml` anywhere else.
|
|
|
|
#### CLI Arguments
|
|
|
|
```yaml title="docker-compose.yml"
|
|
services:
|
|
pangolin-site:
|
|
image: fosrl/pangolin-cli
|
|
container_name: pangolin-site
|
|
restart: unless-stopped
|
|
command:
|
|
- up
|
|
- site
|
|
- --id 31frd0uzbjvp721
|
|
- --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6
|
|
- --endpoint https://app.pangolin.net
|
|
```
|
|
|
|
#### Docker healthcheck
|
|
The site connector supports healthchecks as described in [Configure Sites](/manage/sites/configure-site#param-health-file). This file can be used to do a
|
|
healthcheck from within docker (compose file).
|
|
|
|
We need to define the `HEALTH_FILE` environment variable as well as the healthcheck itself:
|
|
```bash
|
|
environment:
|
|
- HEALTH_FILE=/tmp/healthy
|
|
healthcheck:
|
|
test: ["CMD-SHELL", "[ -f /tmp/healthy ]"]
|
|
interval: 30s
|
|
timeout: 5s
|
|
start_period: 30s
|
|
retries: 3
|
|
```
|
|
|
|
Start the service:
|
|
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
## Platform-Specific Installation
|
|
|
|
### Kubernetes
|
|
|
|
<Note>
|
|
The Kubernetes install still uses the legacy Newt for the Helm chart, namespace, and secret keys shown below.
|
|
</Note>
|
|
|
|
Running a site in a Kubernetes cluster is covered separately from the Docker instructions above, since it uses a dedicated Helm chart rather than a plain `docker run` or Compose file. See:
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="Helm" href="/manage/sites/kubernetes/helm" icon="box">
|
|
Quick-start guide for installing a site with Helm.
|
|
</Card>
|
|
<Card title="Kustomize" href="/manage/sites/kubernetes/kustomize" icon="layer-group">
|
|
Install a site with rendered manifests and Kustomize overlays.
|
|
</Card>
|
|
<Card title="Configuration" href="/manage/sites/kubernetes/configuration" icon="sliders">
|
|
Full configuration reference for Helm and Kustomize workflows.
|
|
</Card>
|
|
<Card title="Troubleshooting" href="/manage/sites/kubernetes/troubleshooting" icon="circle-question">
|
|
Debug site deployment and connection issues in Kubernetes.
|
|
</Card>
|
|
</CardGroup>
|
|
|
|
### Unraid
|
|
|
|
Newt is available in the Unraid Community Applications store. Search for "Newt" and follow the installation prompts. Enter the ID, secret, and endpoint from Pangolin in the template fields.
|
|
|
|
<Frame caption="Newt available in Unraid Community Applications store">
|
|
<img src="/images/unraid_store.png" alt="Newt on CA" />
|
|
</Frame>
|
|
|
|
### Advantech Router App
|
|
|
|
Download the correct version of the router app for your device from the [GitHub releases](https://github.com/fosrl/newt/releases/latest). You can find more information about router apps along with the right version information for your hardware on the the [Advantech engineering portal](https://icr.advantech.com/products/software/router-apps).
|
|
|
|
To install the router app, log into your Advantech router and navigate to the Router Apps section. Upload the downloaded `.tgz` file and follow the prompts to install.
|
|
|
|
<Frame caption="Screenshot of installing the router app on an Advantech router UI">
|
|
<img src="/images/advantech_router_app_install.png" alt="Advantech router UI showing site router app installation" width="400" centered/>
|
|
</Frame>
|
|
|
|
After installation, click on the router app link at the top of the page to configure the app with your site credentials from Pangolin. Once you have entered the credentials, save and start the app. The router will now be connected to your Pangolin site and you can manage it like any other site in the dashboard.
|
|
|
|
<Frame caption="Screenshot of configuring the router app on an Advantech router UI">
|
|
<img src="/images/advantech_router_app_configure.png" alt="Advantech router UI showing site credential configuration" width="400" centered/>
|
|
</Frame>
|
|
|
|
A complete config file is located at `/etc/newt/settings` on the router. You can edit this file directly to change credentials or add additional configuration options. After making changes, restart the router app to apply the new configuration. An example settings file can be found at: https://github.com/fosrl/newt/blob/main/packages/advantech/merge/etc/defaults
|