You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
206 lines
9.9 KiB
Markdown
206 lines
9.9 KiB
Markdown
# 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.
|