Introduces immutability to IPP-USB OCI image (#106)

* Introduce immutability to IPP-USB OCI image
* Update README to include runtime flags for data persistence
* Update documentation for configuration and logging setup
* Include nano in Rock image and improve docs with persistent storage for ipp-usb
* Enhance persistence: Separate volumes for state, config, and logs in ipp-usb.

Author: im0vishal

README.md

@@ -235,76 +235,123 @@ start ipp-usb when needed.
   sudo snap install docker
 ```
 
-#### Step-by-Step Guide
+#### **Running the `ipp-usb` Container with Persistent Storage**  
 
-You can pull the `ipp-usb` Docker image from the GitHub Container Registry.
+To run the `ipp-usb` container while ensuring that its state persists across restarts, follow these steps.  
 
-**From GitHub Container Registry** <br>
-To pull the image from the GitHub Container Registry, run the following command:
+#### **1. Pull the `ipp-usb` Docker Image**  
+The latest image is available on the GitHub Container Registry. Pull it using:  
 ```sh
-  sudo docker pull ghcr.io/openprinting/ipp-usb:latest
+sudo docker pull ghcr.io/openprinting/ipp-usb:latest
 ```
 
-To run the container after pulling the image, use:
+#### **2. Create Persistent Storage Volumes**  
+To ensure that configuration settings and printer state persist across container restarts, create two Docker volumes:  
+
 ```sh
-  sudo docker run -d --network host \
-      -v /dev/bus/usb:/dev/bus/usb:ro \
-      --device-cgroup-rule='c 189:* rmw' \
-      --name ipp-usb \
-      ghcr.io/openprinting/ipp-usb:latest
-```
+sudo docker volume create ipp-usb-state
+sudo docker volume create ipp-usb-conf
+```  
+
+These volumes store:  
 
-- `--network host`: Uses the host network, ensuring IPP-over-USB and Avahi service discovery work correctly.
-- `-v /dev/bus/usb:/dev/bus/usb:ro`: Grants the container read-only access to USB devices.
-- `--device-cgroup-rule='c 189:* rmw'`: Grants the container permission to manage USB devices (189:* covers USB device nodes).
+- **`ipp-usb-state` (`/var/ipp-usb/`)**  
+  - Device state files (`/var/ipp-usb/dev/`) – Ensures stable TCP port allocation and DNS-SD name resolution.  
+  - Lock files (`/var/ipp-usb/lock/`) – Prevents multiple instances from running simultaneously.  
+  - Log files (`/var/log/ipp-usb/`) – Can be optionally mounted if needed for debugging.  
+
+- **`ipp-usb-conf` (`/etc/ipp-usb/`)**  
+  - Configuration file (`/etc/ipp-usb/ipp-usb.conf`) – Stores user-defined settings.  
+  - Quirks files (`/etc/ipp-usb/quirks/`) – Contains printer-specific workarounds.  
+
+#### **3. Run the Container with Required Mounts**  
+Start the container with appropriate options:  
 
-To check the logs of `ipp-usb`, run:
 ```sh
-  sudo docker logs -f ipp-usb
+sudo docker run -d --network host \
+    -v /dev/bus/usb:/dev/bus/usb:ro \
+    -v ipp-usb-state:/var/ipp-usb \
+    -v ipp-usb-conf:/etc/ipp-usb \
+    --device-cgroup-rule='c 189:* rmw' \
+    --name ipp-usb \
+    ghcr.io/openprinting/ipp-usb:latest
 ```
 
+- **`--network host`** → Uses the host’s network to enable proper IPP-over-USB and Avahi service discovery.  
+- **`-v /dev/bus/usb:/dev/bus/usb:ro`** → Grants read-only access to USB devices for printer detection.  
+- **`-v ipp-usb-state:/var/ipp-usb`** → Mounts the persistent storage volume for printer state, lock files, and logs.  
+- **`-v ipp-usb-conf:/etc/ipp-usb`** → Ensures configuration and quirks files persist across reboots.  
+- **`--device-cgroup-rule='c 189:* rmw'`** → Grants read, write, and management permissions for USB printers inside the container.  
+
+
 ### Building and Running `ipp-usb` Locally
 
 #### Prerequisites
 
-**Docker Installed**: Ensure Docker is installed on your system. You can download it from the [official Docker website](https://www.docker.com/get-started) or from the Snap Store:
+1. **Docker Installed**: Ensure Docker is installed on your system. You can download it from the [official Docker website](https://www.docker.com/get-started) or from the Snap Store:
 ```sh
   sudo snap install docker
 ```
 
-**Rockcraft**: Rockcraft should be installed. You can install Rockcraft using the following command:
+2. **Rockcraft**: Rockcraft should be installed. You can install Rockcraft using the following command:
 ```sh
   sudo snap install rockcraft --classic
 ```
 
-#### Step-by-Step Guide
-
-**Build the `ipp-usb` Rock Image**
+**To Build and Run the `ipp-usb` Rock Image Locally, follow these steps** 
 
-The first step is to build the Rock from the `rockcraft.yaml`. This image will contain all the configurations and dependencies required to run `ipp-usb`.
+#### **1. Build the `ipp-usb` Rock Image**  
+The first step is to build the Rock image from the `rockcraft.yaml` configuration file. This image will include all required dependencies and configurations for `ipp-usb`.  
 
-Navigate to the directory containing `rockcraft.yaml`, then run:
+Navigate to the directory containing `rockcraft.yaml` and run:  
 ```sh
   rockcraft pack -v
-```
+```  
 
-**Compile to Docker Image**
+#### **2. Convert the Rock Image to a Docker Image**  
+Once the `.rock` file is built, convert it into a Docker image using:  
+```sh
+sudo rockcraft.skopeo --insecure-policy copy oci-archive:<rock_image> docker-daemon:ipp-usb:latest
+```  
+
+#### **3. Create Persistent Storage Volumes**  
+To ensure that configuration settings and printer state persist across container restarts, create two Docker volumes:  
 
-Once the `.rock` file is built, compile a Docker image from it using:
 ```sh
-  sudo rockcraft.skopeo --insecure-policy copy oci-archive:<rock_image_name> docker-daemon:ipp-usb:latest
-```
+sudo docker volume create ipp-usb-state
+sudo docker volume create ipp-usb-conf
+```  
 
-**Run the `ipp-usb` Docker Container**
+These volumes store:  
+
+- **`ipp-usb-state` (`/var/ipp-usb/`)**  
+  - Device state files (`/var/ipp-usb/dev/`) – Ensures stable TCP port allocation and DNS-SD name resolution.  
+  - Lock files (`/var/ipp-usb/lock/`) – Prevents multiple instances from running simultaneously.  
+  - Log files (`/var/log/ipp-usb/`) – Can be optionally mounted if needed for debugging.  
+
+- **`ipp-usb-conf` (`/etc/ipp-usb/`)**  
+  - Configuration file (`/etc/ipp-usb/ipp-usb.conf`) – Stores user-defined settings.  
+  - Quirks files (`/etc/ipp-usb/quirks/`) – Contains printer-specific workarounds.  
+
+#### **4. Run the Container with Required Mounts**  
+Start the container with appropriate options:  
 
 ```sh
-  sudo docker run -d --network host \
-      -v /dev/bus/usb:/dev/bus/usb:ro \
-      --device-cgroup-rule='c 189:* rmw' \
-      --name ipp-usb \
-      ipp-usb:latest
+sudo docker run -d --network host \
+    -v /dev/bus/usb:/dev/bus/usb:ro \
+    -v ipp-usb-state:/var/ipp-usb \
+    -v ipp-usb-conf:/etc/ipp-usb \
+    --device-cgroup-rule='c 189:* rmw' \
+    --name ipp-usb \
+    ipp-usb:latest
 ```
 
+- **`--network host`** → Uses the host’s network to enable proper IPP-over-USB and Avahi service discovery.  
+- **`-v /dev/bus/usb:/dev/bus/usb:ro`** → Grants read-only access to USB devices for printer detection.  
+- **`-v ipp-usb-state:/var/ipp-usb`** → Mounts the persistent storage volume for printer state, lock files, and logs.  
+- **`-v ipp-usb-conf:/etc/ipp-usb`** → Ensures configuration and quirks files persist across reboots.  
+- **`--device-cgroup-rule='c 189:* rmw'`** → Grants read, write, and management permissions for USB printers inside the container.  
+
 ### Accessing the Container Shell
 
 To enter the running `ipp-usb` container and access a shell inside it, use:
@@ -313,22 +360,105 @@ To enter the running `ipp-usb` container and access a shell inside it, use:
 ```
 This allows you to inspect logs, debug issues, or manually run commands inside the container.
 
-### Configuration
+### Configuration  
 
-The `ipp-usb` container uses a configuration file located at:
+The `ipp-usb` container uses a configuration file located at:  
+```sh
+/etc/ipp-usb/ipp-usb.conf
 ```
-/etc/ipp-usb.conf
+By default, the container uses the built-in configuration, which can be modified from inside the container. 
+
+**Modifying the Configuration File Inside the Container**  
+
+#### **1. Enter the Running Container**  
+Use the following command to access the container’s shell:  
+```sh
+sudo docker exec -it ipp-usb bash
 ```
-To customize the configuration, mount a modified config file:
+
+#### **2. Open the Configuration File in Nano**  
+Once inside the container, open the configuration file using `nano`:  
 ```sh
-  sudo docker run -d --network host \
-      -v /dev/bus/usb:/dev/bus/usb:ro \
-      --device-cgroup-rule='c 189:* rmw' \
-      -v /path/to/custom/ipp-usb.conf:/etc/ipp-usb.conf:ro \
-      --name ipp-usb \
-      ghcr.io/openprinting/ipp-usb:latest
+nano /etc/ipp-usb/ipp-usb.conf
 ```
 
+#### **3. Edit and Save the File**  
+- Make the necessary changes to the file.  
+- Press `CTRL + X`, then `Y`, and hit `Enter` to save the changes.  
+
+#### **4. Restart the Container to Apply Changes**  
+Exit the container and restart it to apply the updated configuration:  
+```sh
+sudo docker restart ipp-usb
+```
+
+### **Viewing Logs in the `ipp-usb` Container**  
+
+The `ipp-usb` container logs important events and errors to `/var/log/ipp-usb/`. Logs are categorized into:  
+
+- **Main log file:** `/var/log/ipp-usb/main.log` → Captures overall service activity, including errors and general events.  
+- **Per-device logs:** `/var/log/ipp-usb/<DEVICE>.log` → Individual log files for each detected printer, helpful for troubleshooting device-specific issues.  
+
+#### **1. Using Docker Logs**  
+
+To view real-time logs from the running container, use:  
+```sh
+sudo docker logs -f ipp-usb
+```  
+- The `-f` flag follows the logs in real-time.  
+- Replace `ipp-usb` with your actual container name if different.  
+
+#### **2. Viewing Logs Inside the Container**  
+
+If you need to inspect logs manually, first enter the container shell:  
+```sh
+sudo docker exec -it ipp-usb bash
+```  
+
+Once inside the container, you can use the following commands:  
+
+#### **2.1 Monitor Logs in Real-Time**  
+
+- **Main log file:**  
+  ```sh
+  tail -f /var/log/ipp-usb/main.log
+  ```  
+  This continuously displays new log entries for the entire service.  
+
+- **Per-device log file (Replace `<DEVICE>` with your printer's identifier):**  
+  ```sh
+  tail -f /var/log/ipp-usb/<DEVICE>.log
+  ```  
+
+#### **2.2 Display Full Log Files**  
+
+- **Show full contents of the main log file:**  
+  ```sh
+  cat /var/log/ipp-usb/main.log
+  ```  
+
+- **Show logs for a specific device:**  
+  ```sh
+  cat /var/log/ipp-usb/<DEVICE>.log
+  ```  
+
+#### **2.3 List Available Device Logs**  
+
+To see all available per-device log files, run:  
+```sh
+ls /var/log/ipp-usb/
+```  
+
+#### **3. Persisting Logs Across Container Restarts**  
+
+If you want logs to persist across container restarts, you should mount the log directory using a Docker volume or a host directory.  
+
+**Required Docker Flags for Log Persistence:**  
+- `-v <volume-name>:/var/log/ipp-usb` → Mounts a Docker volume for log persistence.  
+- **or**  
+- `-v <host-directory>:/var/log/ipp-usb` → Mounts a host directory to retain logs outside the container.  
+
+These options ensure that logs remain available even after the container stops or is recreated, allowing for easier troubleshooting and auditing.
 
 ## Installation from source