Feat/20

.github/workflows/ci.yml

@@ -1,4 +1,4 @@
-on: [push, pull_request]
+on: [pull_request]
 name: CI
 jobs:
   test:
@@ -43,4 +43,7 @@ jobs:
             mkdocs-material-
       - run: pip install -r requirements.txt
       - run: DEBIAN_FRONTEND=noninteractive sudo apt install -y libcairo2
-      - run: mike deploy test
+      - name: mike deploy test
+        run: |
+          export SANDAL_GOLANG_LIB_URL=https://pkg.go.dev/github.com/ahmetozer/sandal@${{ steps.version.outputs.VERSION }}/pkg/lib
+          mike deploy test

.github/workflows/release.yml

@@ -2,7 +2,7 @@ on:
   push:
     tags:
       - 'v*'  # This will match tags that start with 'v', like v1.0.0
-name: CI
+name: Release
 jobs:
   test:
     name: Build Test
@@ -70,5 +70,6 @@ jobs:
           echo "VERSION=$VERSION" >> $GITHUB_OUTPUT
       - name: Deploy docs with mike
         run: |
+          export SANDAL_GOLANG_LIB_URL=https://pkg.go.dev/github.com/ahmetozer/sandal@${{ steps.version.outputs.VERSION }}/pkg/lib
           mike deploy --push --update-aliases ${{ steps.version.outputs.VERSION }} latest
           mike set-default --push latest

docs/guide/daemon.md

@@ -0,0 +1,51 @@
+# Daemon
+
+You can start your containers with run command but for following requirements suggested to use daemon service instead of standalone.
+
+- Automatically starting containers at the boot
+- Rerun container when process is exits
+- Work with read-only disk system and keep current state at memory
+- Reduce read and write calls to system disk for updating or getting state information
+
+## Registering the Service
+
+Installation of daemon supports Systemd and Open RC init systems.
+
+```sh
+sandal daemon -install
+```
+
+You can start service with your system init and service controller.
+
+```{ .sh .annotate title="managing" }
+sh title="service control" annote
+# service sandal [start|stop|restart]
+service sandal start # (1)!
+```
+
+1. Output of service command varies between Systemd and OpenRC but it does not have impact.
+
+## Behaviors of Daemon Service
+
+### Service Start
+
+Provisiones containers which they have a `-d` and `--startup` arguments placed while creating with `sandal run` command.
+
+### Service Stop
+
+Daemon has signal proxy to transfer received following signals to containers.
+
+- SIGINT (2)
+- SIGQUIT (3)
+- SIGTERM (15)
+
+If container does not gracefully **shut down in 30 second** when the signal is recived by contianer, daemon itself will send `SIGKILL (9)` to the container for ending the process.
+
+### Container Death
+
+Health check function checks existence of container Process ID (PID), if not, it re-provisions container with same run arguments.
+
+### File Events at Sandal State Directory
+
+In case of manual actions under Sandal state directly, system reads those actions and reloads files into daemon.  
+**Note:** File Events only supported physically attached storage systems. Network attached storage (SMB, NFS) does capable to send those events.

docs/guide/run.md

@@ -0,0 +1,297 @@
+# Run
+
+This sub command provisiones a new container to the system.
+
+``` { .bash .annotate title="Example usage" }
+sandal run -lw / -tmp 10 --rm --  bash
+```
+
+## Flags
+
+| Flag Type   | Description                          |
+| ----------- | ------------------------------------ |
+| `bool`      | by default it is set to false, in case of presence, it will be true.  |
+| `string`    | only accepts single string value. |
+| `value`     | similar to string but multiple presences are accepted |
+
+---
+
+### `-chdir string`
+
+:   container changes will saved this directory (default "/var/lib/sandal/changedir/new-york")
+
+---
+
+### `-d bool`
+
+:   run container in background
+
+---
+
+### `-devtmpfs string`
+
+:   mount point of devtmpfs  
+example: -devtmpfs /mnt/devtmpfs  
+[more info unix.stackexchange.com](https://unix.stackexchange.com/questions/77933/using-devtmpfs-for-dev)
+
+---
+
+### `-dir string`
+
+:   working directory  
+Default it is set to root folder `/`
+
+---
+
+### `-env-all bool`
+
+:   send all enviroment variables to container  
+Environment variables which currently you are seing at `env` command.
+
+---
+
+### `-env-pass value`
+
+:   pass only requested enviroment variables to container  
+For example you are set variable with `export FOO=BAR`, and `-env-pass FOO` will read variable from existing environment and passes to container.  
+***It does not accepts `-env-pass FOO=BAR` for security purposes***
+
+---
+
+### `-help bool`
+
+:   show this help message
+
+---
+
+### `-host-ips string`
+
+:   host interface ips (default "172.16.0.1/24;fd34:0135:0123::1/64")
+
+---
+
+### `-host-net string`
+
+:   host interface for bridge or macvlan (default "sandal0")
+
+---
+
+### `-hosts string`
+
+:   cp (copy), cp-n (copy if not exist), image(use image) (default "cp")  
+Allocation configuration of /etc/hosts file.
+
+---
+
+### `-lw value`
+
+: Lower directory of the root file system  
+  Lower directories are attach folders or images to container to access but changes are saved under `-chdir`.  
+  This flag can usable multiple times to attach multiple images and directories to container.
+
+!!! note
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+massa, nec semper lorem quam in massa.
+!!!
+
+??? info "More"
+
+    Example Commands
+
+    ```bash
+    # Single Lower Directory
+    sandal run -lw /my/dir/lw1 -- bash
+    # Multiple Lower Directories
+    sandal run -lw /my/dir/lw1 -lw /my/dir/lw2 -lw /my/dir/lw3 -- bash
+    # SquashFS # (1)
+    sandal run -lw /my/img/debian.sqfs -lw /my/image/config.sqfs -- bash
+    # Mounting .img file # (2)
+    sandal run -tmp 1000 -lw /my/img/2024-11-19-raspios-bookworm-arm64-lite.img:part=2 \
+    -lw /my/image/config.sqfs --rm -- bash 
+    ```
+
+    1. You can create SquashFS files with `sandal convert`.
+    2. Image files consist of multiple partition, you have to specificly define partition information in commandline.
+      You can find image details with `sandal image info file.img`
+
+    :   #### How Lower Directories Works ?
+
+    :     Read file operation
+
+    ``` mermaid
+    graph LR
+    M1([MyApp]) --Access--> O1[OverlayFs]
+    O1 -- Return File --> M1
+
+    O1[OverlayFs] --> E4
+    E4{Exist at chdir ?} -- Yes | Read from --> C1[(ChangeDir)]
+    E4 -- No | TRY --> E3
+
+    E3{Exist at lw3 ?} -- Yes | Read from --> LW3[(lower3)] 
+    E3 -- No | TRY --> E2
+
+    E2{Exist at lw2 ?} -- Yes | Read from --> LW2[(lower2)] 
+    E2 -- No | TRY --> E1
+
+    E1{Exist at lw3 ?} -- Yes | Read from --> LW1[(lower1)]
+    E1 -- No | File Not Found --> O1
+    ```
+
+    :   Write file operation
+
+    ``` mermaid
+    graph LR
+    M1([MyApp]) --Write--> O1[OverlayFs]
+
+    O1[OverlayFs] --> C1[(ChangeDir)]
+
+    ```
+
+---
+
+### `-name string`
+
+:   name of the container (default "new-york")
+
+---
+
+### `-net-type string`
+
+:   bridge, macvlan, ipvlan (default "bridge")
+
+---
+
+### `-ns-cgroup string`
+
+:   cgroup namespace or host
+
+---
+
+### `-ns-ipc string`
+
+:   ipc namespace or host
+
+---
+
+### `-ns-mnt string`
+
+:   mnt namespace or host
+
+---
+
+### `-ns-net string`
+
+:   net namespace or host
+
+---
+
+### `-ns-ns string`
+
+:   ns namespace or host
+
+---
+
+### `-ns-pid string`
+
+:   pid namespace or host
+
+---
+
+### `-ns-time string`
+
+:   time namespace or host
+
+---
+
+### `-ns-user string`
+
+:   user namespace or host (default "host")
+
+---
+
+### `-ns-uts string`
+
+:   uts namespace or host
+
+---
+
+### `-pod-ips string`
+
+:   container interface ips
+
+---
+
+### `-rdir string`
+
+:   root directory of operating system (default "/")
+
+---
+
+### `-resolv string`
+
+:   cp (copy), cp-n (copy if not exist), image (use image), 1.1.1.1;2606:4700:4700::1111 (provide nameservers) (default "cp")
+
+---
+
+### `-rm bool`
+
+:   remove container files on exit
+
+---
+
+### `-ro bool`
+
+:   read only rootfs
+
+---
+
+### `-rci value`
+
+:   run command before init
+>
+  ```bash
+  sandal run -rm -lw / -rci="ifconfig eth0" -- echo hello
+  ```
+
+---
+
+### `-rcp value`
+
+:   run command before pivoting.  
+>
+  ```bash
+  sandal run -rm -lw / -rci="ifconfig eth0" -- echo hello
+  ```
+
+---
+
+### `-startup`
+
+:   run container at startup by sandal daemon
+
+---
+
+### `-tmp uint`
+
+:   allocate changes at memory instead of disk. Unit is in MB, when set to 0 (default) which means it's disabled.  
+Benefical for:
+:   - Provisioning ephemeral environments
+    - Able to execute sandal under sandal or docker with tmpfs to prevent overlayFs in overlayFs limitations
+    - Reduce disk calls for writing
+    - Work with not supported file systems such as fat32, exfat
+
+---
+
+### `-v value`
+
+:   volume mount point
+>
+  ```bash
+  # chroot to given path
+  sandal run -rm -v /mnt/disk1:/ -- bash
+  #  attach file,attach path to custom path, attach path, and  to the container.
+  sandal run -rm -v /etc/nftables.conf \
+    -v /run/dbus \
+    -v /etc/homeas/config:/config  -- bash
+  ```