lj-packer/README.md

# LJ Packer

### Welcome to LJ Packer,  [LJ](https://git.interhacker.space/teamlaser/LJ) software's virtual machine images provider.

#### Errr... Sorry but what is this "LJ" thing already?
* LJ is used to command multiple _LASERS_ via a _CENTRAL SERVER_
* _CENTRAL SERVER_ exchanges data with _LASERS_ and _POINTS GENERATORS_ on a Local Area Network (LAN)
* _LASERS_ use _[ETHER-DREAMS](https://ether-dream.com/)_ interfaces to connect to _LAN_
* _POINTS GENERATORS_ store their output in a _REDIS_ located on _CENTRAL SERVER_

**The images produced by this code provide _CENTRAL SERVER_ and _REDIS_, plus some help to configure _LAN_.** You will need _LASERS_ and _ETHER-DREAMS_ to get a fully working setup.

## OK, but why?

LJ is written in Python with lots of dependencies and can be a bit difficult to configure, hence the need for such bootable and easily (re)configured system images.

**But be cautious, the images are not safe to run on the Internet AT ALL!** The SSH server is open for root login with a _**VERY**_ simple password:

```
root:laser
```

**Run the images produced with care on local / airtight networks.**

# Images

No official repository for images yet, but this is expected in the future.

# Limitations

All of this has been tested only on Debian 10 Buster. YMMV.

# Crash course

These instructions are for *building* images, see below to *run* images.

You need to [install packer](https://www.packer.io/downloads) first, the syntax is valid with version 1.6+

**Compiling for qemu (recommanded):**

```
sudo apt install qemu qemu-kvm
git clone https://git.interhacker.space/teamlaser/lj-packer
cd lj-packer
# The "no-desktop" install
PACKER_LOG=1 sudo packer build -on-error=ask --only=teamlaser-lj  build.json
# The "desktop" install
PACKER_LOG=1 sudo packer build -on-error=ask --only=teamlaser-lj-xfce  build.json

```

**Compile for LXC (not fully tested, should work):**
```
sudo apt install lxc
PACKER_LOG=1 sudo packer build -on-error=ask --only=teamlaser-lj-lxc  build.json
```

All the compilation should be automatic, and result with images in local directories (output, output)

# Running in KVM

All commands are given for terminal use and probably require root access.



## kvm:user : KVM with simple/no-LAN network

**It is the simple solution, useful for fast testing the software.**
You will access the VM services through "virtual" localhost ports of your machine.
But the VM will not be able to exchange data on LAN.


### kvm:user 0. Rediction of VM Ports to Local Ports

Ports redirections are done so that you can access the VM port.

In our case, we propose to access Port number "N" by adding 10000 to it.

Here are the resulting redirections in the (Localhost:Port) (VM:Port) format:

```
* localhost:10022 SSH (VM:22) i.e. ssh root@localhost -p 10022
* localhost:10080 HTTP (VM:80) i.e. x-www-browser http://localhost:10080
* localhost:10443 HTTPS (VM:443) i.e. x-www-browser https://localhost:10443
* localhost:16379 REDIS (VM:6379) i.e.redis-cli -h localhost -p 16379
* localhost:16454 ARTNET (VM:6454)
* localhost:19001 WEBSOCKET ws (VM:9001)
* localhost:19002 WEBSOCKET SECURE wss (VM:9001)
```


### kvm:user 1. Booting


```
# Choose the XFCE image 
export IMAGE=packer-teamlaser-lj-xfce
# For the non desktop image 
# export IMAGE=packer-teamlaser-lj
```

**Start the VM**

Place yourself in the reposity where you placed the iso file 
```
sudo /usr/bin/qemu-system-x86_64 \
  -m 2048M  -boot once=d \
  -machine type=pc,accel=kvm \
  -display gtk -vnc 127.0.0.1:6 \
  -name ${IMAGE}\
  -drive file=${IMAGE},format=qcow2 \
  -device virtio-net,netdev=user.0 \
  -netdev user,id=user.0,hostfwd=tcp::10022-:22,hostfwd=tcp::10080-:80,hostfwd=tcp::10443-:443,hostfwd=tcp::16379-:6379,hostfwd=tcp::6454-:6454,hostfwd=tcp::19001-:9001,hostfwd=tcp::19002-:9002

```

### kvm:user 2. Connecting to the VM

**If you start the LXDE version, a login box should appear after boot. Use:**

```
   LOGIN   root
   PASS    laser (e.g. lqser for AZERTY keyboards)
```

**With LXDE or not, you can connect using the SSH protocol:**

```
# Wait until ssh/login is available in the VM
# Type password "laser" i.e. "lqser" on AZERTY keyboards
ssh root@localhost -p10022

```


### kvm:user 3. Configure the app

**Some configuration is required to access the web interface**

The app will run an auto-diagnostic, which might fail to connect to network in this mode. 

But it's not so bad: with the ports redirections, it works nonetheless.

When asked for an action, choose `(c)onfigure` in the menu by pressing `c`.

You have now access to the configuration menu.

Configure :
 
* `127.0.0.1` for `#1 The IP address for webui`: press `1`, then type `127.0.0.1`
* `19001` for `#3 	Websocket port` :  press `3`, then type `19001`

Then type `x` to exit. Done!





### kvm:user 4. Start playing

**Start the LJ app on the VM**

```
root@debian:/opt/LJ python3 ./main.py
```

This should start all the required processes.

**Access the web app from the HOST, i.e. your machine**

Open a web browser on [http://locahost:10080].

It should show a 'CONNECTED' message, and the 'Simulator' page show a default parallelogram.

You can now start sending your points to the redis server from your machine and see the result in the web simulator.

With redis installed on your machine:

```
redis-cli -h 127.0.0.1 -p 16379 set '/pl/0/0' '(150.0, 230.0, 65280), (170.0, 170.0, 65280), (230.0, 170.0, 65280), (210.0, 230.0, 65280), (150.0, 230.0, 65280)]'

```




## kvm:bridge KVM with full network access


**It is a more complex solution, useful for real use of LJ with _LASERS_ on _LAN_.**
You will access the VM services through "virtual" localhost ports of your machine.
But the VM will not be able to exchange data on LAN.

Here is the documentation on how to setup a bridge interface on your machine.
It is a bit complex, but follow the instructions and it should be fine...

### kvm:bridge 0. First some variables / names we will use
```
# 0. Names / concepts
HOST      The name used to define your laptop (or any other machine running qemu)
GUEST     The name used to define the qemu virtual machine

# 0. Variables
HOST_IF   The variable for HOST's network interface, the one used for LAN. Ex: eth0, ens3
HOST_IP   The variable for HOST's IP address on the LAN. Ex: 192.168.1.20
IP_RANGE  The variable for size of a the subnet for your LAN. Ex: /24
GUEST_IF  The variable for GUEST's network interface.
GUEST_IP  The variable for GUEST's IP address on the LAN. Ex: 192.168.1.21
SU        The sudo command required if not running as root

## As an Example, here is a working configuration

export HOST_IF=enx9cebe8ce6930
export HOST_IP=192.168.1.99
export IP_RANGE=/24
export SU='sudo '
```

### kvm:bridge 1. Configuring HOST network interfaces
```
# 1. Configure HOST: set up bridge over HOST_IF

$SU ip l set dev ${HOST_IF} down
$SU brctl addbr br0
$SU brctl addif br0 ${HOST_IF}
$SU ip tuntap add tap0 mode tap
$SU brctl addif br0 tap0
$SU iptables -t nat -A POSTROUTING -o br0 -j MASQUERADE
$SU iptables -I FORWARD -i br0 -j ACCEPT
$SU ip l set dev ${HOST_IF} up
$SU ip l set dev br0 up
$SU ip l set dev tap0 up
$SU ip a add ${HOST_IP}${IP_RANGE} dev br0
$SU sysctl net.ipv4.ip_forward=1

##troubleshooting: there must be NO ip address attached to $HOST_IF
$SU ip address show dev ${HOST_IF} | grep global || echo -e "\n\e[31mOops.... Remove all IP addresses from ${HOST_IF}! Use:\e[0m\n\n$SU ip address del (address/range shown above) dev ${HOST_IF}"
```

### kvm:bridge 2. Booting the VM

Notice how the `net` model changed: we have a MAC address and use the `tap` interface to exchange network packets.
```
# Choose the XFCE image 
export IMAGE=packer-teamlaser-lj-xfce

sudo /usr/bin/qemu-system-x86_64\
 -m 2048M  -boot once=d\
 -machine type=pc,accel=kvm\
 -display gtk -vnc 127.0.0.1:6\
 -name ${IMAGE}\
 -drive file=${IMAGE},format=qcow2\
 -net nic,model=virtio,macaddr=00:00:00:00:00:01\
 -net tap,ifname=tap0\
```

### kvm:bridge 3. Configuring GUEST's network

This part may be more or less complex, as a DHCP server might automatically assign an IP address to your VM.

Use the connection via login described below (4.2) : **a script will check the network connectivity on login.**

According to its output,
* *you might be fine*: it will show an IP address which you can use to connect using standard protocols, i.e. SSH, HTTPS, etc.
* *you might be required to configure the network*. In such a case, you will be asked
  * if you want to configure the network with a graphical tool.
      This is an option for expert users.
      It uses the nmtui (network-manager Terminal UI) interface.
      Use <Edit a connection><Add a connection> and to forget to <Activate> your interface
  * to provide the GUEST_IP/RANGE and the GUEST_GW to use.
      - GUEST_IP/RANGE are depending on your HOST_IP in the LAN
      - GUEST_GW is your HOST_IP
  * Also, can do things by yourself with the following commands on GUEST:
  
  ```
  ip address add  ${GUEST_IP}/${IP_RANGE} dev ${GUEST_IF}
  ip route add default via ${HOST_IP}
  ```

### kvm:bridge 4. Connecting

#### kvm:bridge 4.1 Connecting via login

If you started the QEMU with a display, you can connect to it as root.
CAUTION for french users, it as QWERTY keyboard mapping, type`lqser`

```
USER "root"
PASS "laser" # i.e. "lqser" on AZERTY keyboards
```
#### kvm:bridge 4.2 Connecting via SSH

```
# Wait until ssh/login is available in the VM
# Type password "laser" i.e. "lqser" on AZERTY keyboards
ssh root@${GUEST_IP}
```



# Todos
[] Export USB devices
[] template for config.js + include in html pages