Remote development

Developing locally / running remotely

Some features of AIKON are only available on GPU machines (e.g. vectorization, SegSwap similarity, line extraction). To enable all features during development, you can run your code on a remote GPU machine (e.g. passerelle) while coding locally.

1️⃣ SSH config

🎯 GOAL: create a SSH tunnel to access remote machine via proxy server

1. Create or open nano ~/.ssh/config (modify values between <...> with your own):

   # ℹ️ Remove this section if you don't need a proxy server to access remote GPU
   Host proxy
       Hostname <proxy.domain-name>.fr
       User <username-on-proxy>
       PubkeyAcceptedKeyTypes +ssh-rsa
   
   Host <gpu> # host names are arbitrary, change to your liking
       Hostname <ip-address>
       User <username-on-gpu>
       # to access gpu-host:<remote-port> on localhost:<local-port> from your browser
       LocalForward <local-port> 127.0.0.1:<remote-port>
       ForwardX11Trusted yes
       ForwardAgent yes
       ProxyJump proxy # ℹ️ remove this line if not using a proxy server

   LocalForward allows to access locally with localhost:<local-port> the process running on <remote-port> on the GPU If several terminal sessions are opened on your computer, only the first one will be bound the remote port

🎉 You should now be able to connect with your password using ssh <gpu>

2️⃣ SSH keys

🎯 GOAL: remove the need to enter the password to connect in SSH

1. Check if you already have a public key (cat ~/.ssh/id_ed25519.pub) or create a new SSH key pair

   ssh-keygen -t ed25519

2. Copy your public key to proxy server

   ssh proxy "mkdir -p ~/.ssh && touch ~/.ssh/authorized_keys"
   cat ~/.ssh/id_ed25519.pub | ssh proxy "cat >> ~/.ssh/authorized_keys"

3. Copy your public key on gpu server

   ssh <gpu> "mkdir -p ~/.ssh && touch ~/.ssh/authorized_keys"
   cat ~/.ssh/id_ed25519.pub | ssh <gpu> "cat >> ~/.ssh/authorized_keys"

🎉 You should now be able to connect with ssh <gpu>

3️⃣ Add SSH remote key to Github (optional)

🎯 GOAL: allow cloning repository from GitHub with SSH

1. Connect to GPU

   ssh <gpu>

2. Create an SSH key pair on remote

   ssh-keygen -t ed25519

3. Copy the public key to your clipboard

   cat ~/.ssh/id_ed25519.pub

4. Go to GitHub > Settings > SSH and GPG keys > New
5. Paste the public key content

🎉 You should now be able to clone the repository and install the application on GPU:

git clone git@github.com:Aikon-platform/aikon.git
cd aikon
bash setup.sh # you need to define <local-port> to be the same as FRONT_PORT

You can now run the application on GPU and access it from your browser at localhost:<local-port>

bash run.sh

4️⃣ Configure your IDE to work remotely

🎯 GOAL: code locally, execute remotely

You can use VScode, VSCodium (OSS fork of VSCode) or Pycharm to work on remote machine.

PyCharm

This tutorial will focus on Pycharm: you will learn to configure Pycharm to synchronize one of your local projects on a remote server: you code on your computer and Pycharm scp automatically the files.

To summarize:

• you run the application on the remote machine
• you code on your local machine
• you access the remote application on your browser with localhost:<local-port>

Install Pycharm

You can get free JetBrains licence (Pycharm Professional Edition and more) by applying for Student & Teachers educational licence.

You can also download and use the free version.

Create remote directory for the app

1. Connect to remote machine

   ssh <gpu>

2. Create project folder on remote

   mkdir aikon-dev

3. Create virtual environment

   cd aikon-dev
   python3.10 -m venv venv

Configure python interpreter for the Pycharm project

1. Create a new project in Pycharm by cloning repository (Pycharm > Clone repository) or with command line

   git clone git@github.com:Aikon-platform/aikon.git

2. In the lower right corner of the window, select Add interpreter > On SSH…

3. Connect to SSH server
   

4. Configure python interpreter (here for a python environment) ⚠️ No trailing slash at the end of paths

   Location	Remote path to virtual environment (cuda / pip)
   Base interpreter	Remote path to python executable python -c "import sys;print(sys.executable)"
   Sync folder	Path to project folder
   ✅	Make sure automatic upload is checked

   

5. Click Create and the files from your project should be copied on the remote machine (progress bar at the bottom of the window)

Working locally on remote machine

The project file structure should now be synchronized to the remote folder, thus any modification done locally should be mirrored to the distant folder
⚠️ Modifications are synchronized only when the file is saved, thus, if files are modified using git pull or scp for instance, changes will not be dispatched

You can now open a terminal session on the distant server by clicking in the bottom menu on
Terminal > New Predefined Session 🔽 > Select the SSH session that you want

cd aikon-dev
bash setup.sh
bash run.sh

When you want to retrieve some modifications made on the remote machine (.env files, uploaded mediafiles, task results, etc.):

# in your local pycharm terminal

# .env file
scp <gpu>:~/aikon-dev/front/app/config/.env front/app/config/

# mediafiles
scp -r <gpu>:~/aikon-dev/front/app/mediafiles front/app/

# task results (e.g. similarity)
scp -r <gpu>:~/aikon-dev/api/data/similarity/results api/data/similarity/

VSCode

Set up the proprietary Remote Development extension for VSCode.

VSCodium

VSCodium is an open-source fork of VSCode. Basically, the code of VSCode is open, but the binaries are proprietary, and VSCodium offers open-source alternatives of those binaries. Codium has the exact same features as VSCode.

On Codium, the VSCode extension Remote Development can't be used. Instead, use Open Remote - SSH.

See this issue for more details.

Install VSCodium

See the Docs

# macOS install
brew install --cask vscodium

# debian/ubuntu install (you just need to add the repo to apt and then install)
wget -qO - https://gitlab.com/paulcarroty/vscodium-deb-rpm-repo/raw/master/pub.gpg \
    | gpg --dearmor \
    | sudo dd of=/usr/share/keyrings/vscodium-archive-keyring.gpg

echo 'deb [arch=amd64,arm64 signed-by=/usr/share/keyrings/vscodium-archive-keyring.gpg] https://download.vscodium.com/debs vscodium main' \
    | sudo tee /etc/apt/sources.list.d/vscodium.list

sudo apt update && sudo apt install codium

Then, just launch Codium. In a terminal, type:

codium

Install and configure Open Remote - SSH extension

First, install the extension:

1. open the extension menu (ctrl+shift+x)
2. type Open Remote - SSH in the search bar
3. click on the extension
4. then click Install

Then, configure your SSH. You need to edit your ~/.ssh/config file to have access to the remote servers you want to develop on. See 1️⃣ SSH config above.

Code away !

1. open the new Remote explorer tab
2. select your server and click on Connect to host in a new window. A new Codium window connected to your SSH remote device will open.
3. open the Explorer and select your working folder like you would on your local machine.
4. all done 🪩 🪩 🪩

View the app in the browser

2 methods:

• ctrl+shift+p: open the command palette
• type "Copy forwarded port address"
• copy the proper port and open in navigator

OR

• `ctrl+``: open a terinal (if it is not open aldready)
• open the Ports tab
• find the port you want to view in a browser (API, Front...) and open the address shown in the Forwarded address in a navigator

Troubleshooting: manual install

Remote working is done by installing a Codium server on your remote machine. In some cases, it fails.

You will need to install the remote server matching your Codium version and system architecture manually.

Everything here must be run in the remote server. Before proceeding, ensure you have an internet:

curl https://www.wikipedia.org/

If there is an internet access issue, the install won't work. It's very probably a proxy issue

Then, look at the Codium console. It will have outputted an error message, and before that, the entire VSCodium-server install script.

1. copy this script
2. paste it in a file named codium-server-install.sh on the remote server
3. bash codium-server-install.sh