# Air Link
Air Link is a standalone service to manage remote access to an edge device and to install user apps.
[](https://pypi.org/project/air-link/)
[](https://pypi.org/project/air-link/)
[](https://github.com/zauberzeug/air-link/blob/main/LICENSE)
[](https://github.com/zauberzeug/air-link/graphs/commit-activity)
[](https://github.com/zauberzeug/air-link/issues)
[](https://github.com/zauberzeug/air-link/network)
[](https://github.com/zauberzeug/air-link/stargazers)
## Prerequisites
The edge device needs to run a Linux-based OS and have Python >=3.8 installed.
> [!NOTE]
> To install a recent Python version like 3.11, you can use [pyenv](https://github.com/pyenv/pyenv):
>
> ```bash
> # install dependencies
> sudo apt update
> sudo apt install build-essential libssl-dev zlib1g-dev \
> libbz2-dev libreadline-dev libsqlite3-dev curl \
> libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev
>
> # install pyenv
> curl https://pyenv.run | bash
>
> # add pyenv to login shell .profile, maybe also .bashrc, .zshrc, etc. depending on your shell
> # see https://github.com/pyenv/pyenv?tab=readme-ov-file#set-up-your-shell-environment-for-pyenv
> echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.profile
> echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.profile
> echo 'eval "$(pyenv init -)"' >> ~/.profile
>
> # source the bashrc
> source ~/.bashrc
>
> # install Python 3.11
> pyenv install 3.11
> pyenv global 3.11
> ```
## Setup
### 1. Install the Air Link app on an edge device
Air link can be installed using pip.
To run the app automatically after a reboot, you can install it as a system service using its `install` command.
```bash
pip install air-link
air-link install
```
The app is accessible on port 8080 and can be reached via the IP address of the edge device.
> [!NOTE]
> To make the app accessible over an SSH tunnel, you can log into the edge device with the following command:
>
> ```bash
> ssh -L 8888:localhost:8080 <target device>
> ```
>
> The app will then be reachable at `localhost:8888` on the developer machine.
> [!TIP]
> To display the logs of the Air Link service, use the following command:
>
> ```bash
> journalctl -u air-link -f
> ```
>
> The `-f` flag will follow the logs in real-time.
### 2. Access via NiceGUI On Air
To make the Air Link app accessible via NiceGUI On Air, follow these three steps:
1. Register a new device with a fixed region at <https://on-air.nicegui.io>.
2. Enter the token in the top right corner of the Air Link web interface.
3. Restart the Air Link service using the button next to the token.
Air Link will be reachable through the URL provided by NiceGUI On Air, for example <https://europe.on-air.io/zauberzeug/rodja-air-link>.
We strongly suggest to set a fixed region for the device at <https://on-air.nicegui.io> to keep the URL stable.
### 3. Manage SSH keys (optional)
To allow SSH access without a password, you can add SSH keys to the edge device using the Air Link web interface.
Use the key icon in the top right corner to open the SSH key management.
## Usage
### Install User Apps
You can install user apps via the Air Link web interface.
The web interface lists all available packages and provides a button to upload additional ZIP files.
The install button runs the `install.sh` script from the ZIP file and outputs the process in the web interface.
### SSH Login via NiceGUI On Air
Establish an SSH connection to the machine where Air Link is running via proxy jump over the On Air server:
```bash
ssh -J <your_organization>/<your_device_name>@<your_region>.on-air.io <username_on_device>@localhost
```
Explanation:
The combination of organization and device name before the `@<region>.on-air.io` tells the On Air server where to route the SSH login.
The last bit tells SSH with which user you want to log into the edge device
(which is `localhost` after Air Link received the tunneled data from the On Air server).
> [!TIP]
> You can also put the proxy jump into your `~/.ssh/config` to establish a connection with the bash command `ssh my-device`:
>
> ```
> Host my-device
> User <your_username>
> HostName localhost
> ProxyJump <your_organization>/<your_device_name>@<your_region>.on-air.io
> ```
>
> It may also be beneficial to add the following configuration to the host entry:
>
> ```
> StrictHostKeyChecking no
> UserKnownHostsFile /dev/null
> ServerAliveInterval 30
> ForwardAgent yes
> SetEnv GIT_AUTHOR_NAME="Your Name" EMAIL="your.email@example.com"
> ```
## Development
### Design Decisions
- Assume an edge device with a Linux-based OS and Python >=3.8.
- Run side-by-side with user apps, because deploying/breaking a user app should not affect remote access.
- Provide SSH access to the edge device through the websocket tunnel from NiceGUI On Air.
### Testing Locally
1. Start On Air server with `./main.py`.
2. Start Air Link locally with `./main.py` (and let it point to the local On Air server "localhost").
3. Establish an SSH connection to your local machine via proxy jump over the On Air server: `ssh -J zauberzeug/rodja@localhost:2222 rodja@localhost`.
### Formatting
We use [pre-commit](https://github.com/pre-commit/pre-commit) to make sure the coding style is enforced.
You first need to install pre-commit and the corresponding git commit hooks by running the following commands:
```bash
python3 -m pip install pre-commit
pre-commit install
```
After that you can make sure your code satisfies the coding style by running the following command:
```bash
pre-commit run --all-files
```
These checks will also run automatically before every commit.
### Deployment
To deploy a new version of Air Link, add a new tag with the format `vX.Y.Z` and push it to the repository.
The CI pipeline will then build the new version, upload it to PyPI, and create a new draft release on GitHub.
Raw data
{
"_id": null,
"home_page": "https://github.com/zauberzeug/air-link",
"name": "air-link",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0.0,>=3.8.2",
"maintainer_email": null,
"keywords": null,
"author": "Zauberzeug GmbH",
"author_email": "info@zauberzeug.com",
"download_url": "https://files.pythonhosted.org/packages/20/7d/2d361e85639312741e943d17a36a990a36d9a04bd7b0485d821d0997e3af/air_link-0.4.0.tar.gz",
"platform": null,
"description": "# Air Link\n\nAir Link is a standalone service to manage remote access to an edge device and to install user apps.\n\n[](https://pypi.org/project/air-link/)\n[](https://pypi.org/project/air-link/)\n[](https://github.com/zauberzeug/air-link/blob/main/LICENSE)\n[](https://github.com/zauberzeug/air-link/graphs/commit-activity)\n[](https://github.com/zauberzeug/air-link/issues)\n[](https://github.com/zauberzeug/air-link/network)\n[](https://github.com/zauberzeug/air-link/stargazers)\n\n## Prerequisites\n\nThe edge device needs to run a Linux-based OS and have Python >=3.8 installed.\n\n> [!NOTE]\n> To install a recent Python version like 3.11, you can use [pyenv](https://github.com/pyenv/pyenv):\n>\n> ```bash\n> # install dependencies\n> sudo apt update\n> sudo apt install build-essential libssl-dev zlib1g-dev \\\n> libbz2-dev libreadline-dev libsqlite3-dev curl \\\n> libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev\n>\n> # install pyenv\n> curl https://pyenv.run | bash\n>\n> # add pyenv to login shell .profile, maybe also .bashrc, .zshrc, etc. depending on your shell\n> # see https://github.com/pyenv/pyenv?tab=readme-ov-file#set-up-your-shell-environment-for-pyenv\n> echo 'export PYENV_ROOT=\"$HOME/.pyenv\"' >> ~/.profile\n> echo 'command -v pyenv >/dev/null || export PATH=\"$PYENV_ROOT/bin:$PATH\"' >> ~/.profile\n> echo 'eval \"$(pyenv init -)\"' >> ~/.profile\n>\n> # source the bashrc\n> source ~/.bashrc\n>\n> # install Python 3.11\n> pyenv install 3.11\n> pyenv global 3.11\n> ```\n\n## Setup\n\n### 1. Install the Air Link app on an edge device\n\nAir link can be installed using pip.\nTo run the app automatically after a reboot, you can install it as a system service using its `install` command.\n\n```bash\npip install air-link\nair-link install\n```\n\nThe app is accessible on port 8080 and can be reached via the IP address of the edge device.\n\n> [!NOTE]\n> To make the app accessible over an SSH tunnel, you can log into the edge device with the following command:\n>\n> ```bash\n> ssh -L 8888:localhost:8080 <target device>\n> ```\n>\n> The app will then be reachable at `localhost:8888` on the developer machine.\n\n> [!TIP]\n> To display the logs of the Air Link service, use the following command:\n>\n> ```bash\n> journalctl -u air-link -f\n> ```\n>\n> The `-f` flag will follow the logs in real-time.\n\n### 2. Access via NiceGUI On Air\n\nTo make the Air Link app accessible via NiceGUI On Air, follow these three steps:\n\n1. Register a new device with a fixed region at <https://on-air.nicegui.io>.\n2. Enter the token in the top right corner of the Air Link web interface.\n3. Restart the Air Link service using the button next to the token.\n\nAir Link will be reachable through the URL provided by NiceGUI On Air, for example <https://europe.on-air.io/zauberzeug/rodja-air-link>.\nWe strongly suggest to set a fixed region for the device at <https://on-air.nicegui.io> to keep the URL stable.\n\n### 3. Manage SSH keys (optional)\n\nTo allow SSH access without a password, you can add SSH keys to the edge device using the Air Link web interface.\nUse the key icon in the top right corner to open the SSH key management.\n\n## Usage\n\n### Install User Apps\n\nYou can install user apps via the Air Link web interface.\nThe web interface lists all available packages and provides a button to upload additional ZIP files.\nThe install button runs the `install.sh` script from the ZIP file and outputs the process in the web interface.\n\n### SSH Login via NiceGUI On Air\n\nEstablish an SSH connection to the machine where Air Link is running via proxy jump over the On Air server:\n\n```bash\nssh -J <your_organization>/<your_device_name>@<your_region>.on-air.io <username_on_device>@localhost\n```\n\nExplanation:\nThe combination of organization and device name before the `@<region>.on-air.io` tells the On Air server where to route the SSH login.\nThe last bit tells SSH with which user you want to log into the edge device\n(which is `localhost` after Air Link received the tunneled data from the On Air server).\n\n> [!TIP]\n> You can also put the proxy jump into your `~/.ssh/config` to establish a connection with the bash command `ssh my-device`:\n>\n> ```\n> Host my-device\n> User <your_username>\n> HostName localhost\n> ProxyJump <your_organization>/<your_device_name>@<your_region>.on-air.io\n> ```\n>\n> It may also be beneficial to add the following configuration to the host entry:\n>\n> ```\n> StrictHostKeyChecking no\n> UserKnownHostsFile /dev/null\n> ServerAliveInterval 30\n> ForwardAgent yes\n> SetEnv GIT_AUTHOR_NAME=\"Your Name\" EMAIL=\"your.email@example.com\"\n> ```\n\n## Development\n\n### Design Decisions\n\n- Assume an edge device with a Linux-based OS and Python >=3.8.\n- Run side-by-side with user apps, because deploying/breaking a user app should not affect remote access.\n- Provide SSH access to the edge device through the websocket tunnel from NiceGUI On Air.\n\n### Testing Locally\n\n1. Start On Air server with `./main.py`.\n2. Start Air Link locally with `./main.py` (and let it point to the local On Air server \"localhost\").\n3. Establish an SSH connection to your local machine via proxy jump over the On Air server: `ssh -J zauberzeug/rodja@localhost:2222 rodja@localhost`.\n\n### Formatting\n\nWe use [pre-commit](https://github.com/pre-commit/pre-commit) to make sure the coding style is enforced.\nYou first need to install pre-commit and the corresponding git commit hooks by running the following commands:\n\n```bash\npython3 -m pip install pre-commit\npre-commit install\n```\n\nAfter that you can make sure your code satisfies the coding style by running the following command:\n\n```bash\npre-commit run --all-files\n```\n\nThese checks will also run automatically before every commit.\n\n### Deployment\n\nTo deploy a new version of Air Link, add a new tag with the format `vX.Y.Z` and push it to the repository.\nThe CI pipeline will then build the new version, upload it to PyPI, and create a new draft release on GitHub.\n",
"bugtrack_url": null,
"license": null,
"summary": "Provide SSH access, diagnostics and administration for your edge devices.",
"version": "0.4.0",
"project_urls": {
"Homepage": "https://github.com/zauberzeug/air-link",
"Repository": "https://github.com/zauberzeug/air-link"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "420a3c0bd8ea163a88bcdff9dea7607f4ec893c53387f573ff8ce2646b624337",
"md5": "7baf7359dc9eb24d65574766e9dd2036",
"sha256": "e7f74217376b8864cc834b1b47f1bb3a67706eae69347fd51813443201379b9f"
},
"downloads": -1,
"filename": "air_link-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7baf7359dc9eb24d65574766e9dd2036",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0.0,>=3.8.2",
"size": 13593,
"upload_time": "2024-10-04T11:53:24",
"upload_time_iso_8601": "2024-10-04T11:53:24.271107Z",
"url": "https://files.pythonhosted.org/packages/42/0a/3c0bd8ea163a88bcdff9dea7607f4ec893c53387f573ff8ce2646b624337/air_link-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "207d2d361e85639312741e943d17a36a990a36d9a04bd7b0485d821d0997e3af",
"md5": "41ed249eaa9157c4765b21e61fa247ca",
"sha256": "5879bc9af0b760f0c9511e54c04c2a11f5ee6fd5c579be715899ca0f985c3d9b"
},
"downloads": -1,
"filename": "air_link-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "41ed249eaa9157c4765b21e61fa247ca",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0.0,>=3.8.2",
"size": 12923,
"upload_time": "2024-10-04T11:53:25",
"upload_time_iso_8601": "2024-10-04T11:53:25.826599Z",
"url": "https://files.pythonhosted.org/packages/20/7d/2d361e85639312741e943d17a36a990a36d9a04bd7b0485d821d0997e3af/air_link-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-04 11:53:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "zauberzeug",
"github_project": "air-link",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "air-link"
}
JSON
