imageviewer/README.md

# ImageViewer System

The "ImageViewer" system builds up a Debian system,
where normal users can only cycle through local pictures very easily,
while administrators can add new pictures by copying them from local mass storages (like USB or CD)
and have system access if required.
Administrators do not require knowledge about Linux or Debian to edit the available pictures,
but for customizing the system to your special case may require further experience.
After applying required customizations to the playbook and creating the installation medium,
the installation itself does not require specific knowledge about Linux or Debian.

## Localization of project

This project is currently targeted to German users
due to the origin of the project
(means the Debian system will be configured to use German defaults
and messages and prompts can only be displayed in German for now).
The project will be translated to English in the next time
while a general project for building custom Debian kiosk systems will be extracted.
Code comments are already written in English.

## Implementation

This project modifies a Debian installation iso to prepare an unattended installation of Debian,
after which an Ansible playbook will be executed automatically to configure the ImageViewer itself.
Following a second reboot the system is fully configured and usable.
The only interactionsrequired are at the beginning to start the automatic installation
and at the end to change the preconfigured password and confirm the second reboot.
If you install the system from an USB mass storage,
you may need to remove this manually while the system reboots the first time
to prevent the installer from booting up again.

The system also supports updating itself,
which means that the repository (by default [this](https://git.banananet.work/zocker/imageviewer)) with the playbook will be downloaded and executed again.
Because of Ansible's indempotence principle only changes will be applied
and no reinstallation of the complete system is required.
Parameters especially configured while the installation of Debian

By default, Debian only installs free software and drivers,
so if you need propertary drivers for your processor or graphics card,
you need to apply them manually.

This project is tested with the netinst installation medium for Debian Buster (10.2) on amd64,
however other mediums, versions and architectures should work too.
Using other distributions (easier if deriviated of Debian, e.g. Ubuntu)
should work after required adapations to the preseed configuration and playbook.

This project uses following (visible or important) applications (which are NOT distributed by this repository but by the Debian mirrors):
- Debian GNU/Linux as base system
- Ansible for configuring the system after installation
- Git for cloning playbook while update is applied
- Plymouth for boot up animation
- LightDM as session manager (a.k.a. auto login and login screen)
- i3 as window manager (a.k.a. desktop environment)
- URvxt as terminal emulator
- Python 3 for custom gallery navigator (in kiosk mode)
- imv for displaying pictures (in kiosk mode)
- PCman File Manager as file manager (in admin mode)
- Network Manger for network configuration (in admin mode)
To see the full list,
read the Ansible playbook.

## Creating installation medium

So far the installation medium itself can only be created on Linux systems.

1. Confirm the configuration applied to the installation medium and by the playbook.
   Adapt to your requirements.
   **The current configuration is especially targeted for the original scope of application,
   to use the system in production, you will need to adapt some titles and messages.**
2. Navigate into the `debian-inst` directory
3. Execute make (default target is sufficient)
4. Distribute file `modified.iso`

## Installation using modified medium

**The installation medium will select the first hard drive available and wipe it completely,
do not boot the medium on systems where storage mediums with required data is inserted.**

The computer will require a connection to the internet while installing and configuring the system.
After the second reboot no further connection will be required.

1. Burn ISO to cd OR copy on USB mass storage while preserving boot ability
2. Insert medium into target system and boot from medium
3. Select "Installiere ImageViewer" (German so far)
4. Wait for the installer to install Debian on the only available hard drive.
   If the installer cannot connect to the Debian mirrors or finds multiple hard drives,
   you may require to interact with the installer manually.
5. While the system reboots the first time, remove the installation medium if the system could not eject it by itself (e.g. USB mass storage)
6. Ensure the system boots into the fresh installed Debian.
   No interaction should be required.
   If the system requires your interaction before beginning to configure the system,
   the fresh installed Debian cannot be booted.
   You should contact a person with knowledge about Linux or retry the complete installation.
7. Wait for the playbook to be executed.
   You will see multiple tasks to be executed and finished with the output "changed" or "okay".
8. After configuring the system the admin password will be revealed to you.
   You can change the password or keep it,
   but remember the password!
9. Restart the system a second time, disconnect it of the Internet and enjoy the ImageViewer.

## Usage of the system

### For users

A list of directories will be presented to you.
Renamed by the administrators, these can be categories, locations or anything else.
You can navigate through them using following keybinds:

- Up (arrow key), k (vim binding): Select previous directory
- Down (arrow key), j (vim binding): Select next directory
- Escape, Backspace, q, Left (arrow key), h (vim binding): Exit directory
- Enter/Return, Space, Right (arrow key), l (vim binding): Enter directory

Exiting the first directory does not work.
If you open up a gallery (directory only containing pictures),
the pictures will displayed to you in alphabetical order.
To navigate through the pictures or exit the viewer by using:

- Left (arrow key), Up (arrow key), k (vim binding): Show previous picture
- Right (arrow key) Down (arrow key), j (vim binding): Show next picture
- Escape, BackSpace, q, h (vim binding): Exit viewer

You will loop over all pictures in the directory.

### For administrators

For further reference, the system can run two modes, kiosk mode and admin mode.
Kiosk mode is the default after reboot and allows users to navigate through stored pictures.
Admin mode can be entered after entering a password
and allows changing the pictures and change the configuration of the system.

*The meta key on the keyboard is often called and labeled as Windows key on most keyboards.*

Following commands are available in kiosk mode and admin mode (not on the login screen):
- Control + Meta + s: Shutdown system
- Control + Meta + r: Reboot system

You can also shutdown the system using the power key of the computer
or using Shift+q in kiosk mode.

To change to admin mode,
press Meta + Shift + e.
The login screen will appear,
where you can enter the credentials for the admin account.
To go back to kiosk mode,
simply restart the system (better way will be implemented).

In admin mode you can navigate through the workspaces by pressing Meta+1 to 3
or selecting the desired workspace at the bottom using the mouse cursor.
The status bar at the bottom of the screen shows the current workspace,
current Internet connectivity, battery state and time.

The first workspace allows viewing all stored pictures,
moving, renaming or removing them,
and adding pictures from other storages.
Just insert a USB mass storage device,
a dialog should allow you to open the contents of the mass storage device.
After you are finished copying the images to the hard drive,
remove the USB device from the computer.
You should not change files on the USB device,
otherwise you will need to eject the USB device in the file manager before removing it from the computer.

You can sort the pictures in directories as you like.
Directories with directories inside will be displayed to the user as galleries with other galleries inside,
directories containing only pictures will be displayed to the user as picture queue if he or she opens the directory.
Directories and pictures can contain any chars inside their name, including spaces and special chars, except `/`.

The second workspace allows configuring network connections,
especially wireless network connections,
to prepare for updates.
Navigate through the available options using the arrow keys, Tab and Enter/Return.

The third workspace shows a terminal, where shell commands can be executed.
Please be patient as you can modify the complete system using this.
By entering the command `passwd`, you can change the password, if you wish so.

To update the system, press Meta + Control + u in admin mode.
Before trigger the update process,
please ensure the system has enough battery (or is connected to AC)
and is connected to the internet.

## License

```
ImageViewer for kiosk systems with mostly unattended installation
Copyright (C) 2020  Felix Stupp

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.
```

The test images in `playbook/test-images.tar.gz` are from the Debian project and the Unsplash project
and can be further distributed under GNU GPL v3.0.
See `LICENSE` file for the full license.