artikel / ugai a native openwrt webapp for calibre ebooks

Ugai a Native OpenWRT WebApp for Calibre eBooks

Ugai a Native OpenWRT WebApp for Calibre eBooks

If you're looking to set up home digital storage for private collections, sharing only with family or guests (not strangers on social media), ugai.cgi is the perfect choice. It's also ideal for teachers and trainers, offering an affordable alternative to whiteboards and expensive projectors, turning smartphones into small presentation screens.

Pronounced ooh-guy, this application enables rapid sharing of multimedia collections through any old router. With ugai.cgi, you can establish a portable, Calibre wireless server in under a minute. No advanced IT skills required! Just type 4 simple commands on terminal.

Born from a decade of experience in creating wireless digital libraries for remote Indonesian communities, this budget-friendly innovation costs only about $10 per unit. Perfect for volunteers and educators in resource-strapped areas, ugai.cgi is more than just a digital bookshelf; it also provides bite-sized, Instagram-style micro-learning experiences, making education both accessible and engaging.

Discover the simplicity and speed of the installation process in this video.

This video is intentionally presented without sound, adhering to the principle that 'actions speak louder than words'. Please activate closed captions for detailed descriptions of the actions on screen. Closed captions are available in multiple languages, with Bahasa Indonesia as the default setting.

What's New?

Discover the unique features of this system compared to other wireless server systems utilizing a router as a mini web server:

  • ugai.cgi, tailored for Linux OpenWRT 12.09, runs natively, bypassing the need for interpreters like Python, Perl, or PHP. This efficiency results in significantly faster performance and less energy.
  • It operates directly on the hardware without requiring a traditional rootfs system, simplifying setup for beginners and enhancing energy efficiency.
  • Compatible with both EXT4 and FAT32 partitions, ugai.cgi enables users across all modern operating systems to easily modify content.
  • Features integration with Calibre, a leading digital data management application, providing a user-friendly interface for managing content through the Calibre Desktop app version 3.4.80.
  • The 2024 edition of ugai.cgi supports multiple Calibre databases simultaneously, improving performance by distributing data across separate databases. This capability allows for efficient management of extensive collections within MBR partition limits.
  • Installation is quick and easy, taking less than a minute with just four command lines in the console—making it accessible for anyone.
  • The ugai.cgi web server code is freely available under the MIT license, offering an educational tool for students to learn HTML, CSS, JavaScript, and server management at a low cost, with minimal energy consumption and rapid deployment.

Getting Started

Firmware

Download the OpenWRT 12.09 firmware that includes USB/HDD media reader integration in the kernel to simplify installation. Choose the firmware appropriate for your router. Incorrect installation at this stage can permanently damage your router (bricked). Below are the recommended routers based on real-world experience, cost-effectiveness, and ease of use.

  • TP-Link MR3420 V1 FAT32 This is the most economical tool for managing up to 128GB on USB flash drives and up to 250GB on hard drives. It cost total only 18 US dollar with 320GB brand new SATA hardisk. If you using reused SATA hardisk, this cost will be cheaper.

  • TP-Link WR1043nd V1 FAT32 | TP-Link WR1043nd V1 EXT4
    This device is suitable for heavy usage with data needs up to 1TB.

  • TP-Link MR3020 V1 FAT32 | TP-Link MR3020 V1 EXT4
    Ideal for creating a mobile wireless server powered by a power bank or a static wireless server running on solar panels with small battery pack. MR3020 consume around 1-watt-hour. Since ugai.cgi does not operate using the rootfs method, there is a minimal chance of system failure in the event of a sudden power outage or a drop in current. You can be more confident using ugai.cgi to run a digital wireless library on a remote island with only solar panels as your power source, compared to other systems that operate over rootfs.

This video show exactly how to flash.

Storage Media

The ugai.cgi system handles size seamlessly. However, performance degrades when a single Calibre database system exceeds 7,000 collections, each with more than 10 keywords. But you can split yout collections into diferent Calibre database system. Assume you have 1TB and hundreds thousands video, music, ebook; then you can split by media type. If your collection, let's say, videos exceeds 7.000, then you can split videos by subject. Therefore, the choice of storage media depends more on the router's ability to supply power.

Generally, only the WR1043nd is stable enough for using a 2.5-inch SATA hard disk, provided its power consumption is below 1,000 mA. The MR3420 can handle up to a 320GB 2.5-inch SATA hard disk. The MR3020 is suitable for USB drives up to 128GB.

Format the storage media with the FAT32 system in a single partition.

Download the Code

  • Download the ugai.cgi code from GitHub. Familiar users can pull the ugai.cgi code using the following command in Windows PowerShell or a macOS/Linux terminal:
git clone https://github.com/undix/ugai.git
  • Extract and rename the directory to ugai. Ensure the directory structure on the storage media is as follows:
ugai
├── install
└── www 

Configuration

config.txt

Users can modify the configuration file named config.txt using a text editor like Notepad. The default demo settings are as follows:

current_ip_address='192.168.1.1'        # OpenWRT default
my_ip_address='192.168.1.1'             # your new ip address, default 192.168.1.1
my_time_zone='WIB-9'                    # change to your actual timezone, default UTC+9
my_server_domain='komugai.lan'          # domain and hostname
my_ssid="'Komugai'"                     # SSID change as you pleased
my_ssid_passwd="none"                   # SSID password, default none means passwordless
my_partition='/dev/sda1'                # your partition, do not change unless necessary
my_mount_point='/mnt/usb'               # your mount point, do not change unless necessary
my_format='vfat'                        # vfat OR ext4 
my_max_clients=32                       # maximum clients at a time

config.json

Change this value if necessary.

  • server - server IP address or name, must exactly the same as config.txt above
  • dir - directory where you put all off Calibre database (physical or just link)
  • name - default Calibre database as home

You will have error page if ugai.cgi failed to find default Calibre database as home.

{
    "server": "http://192.168.1.1",
    "dir": "data", 
    "name": "komugai"
}

This file will be rename to .config.json every boot. If you need to change later, change your Windows file manager view with CTRL+H to display all hidden files and directories.

navigation.txt

This is navigation system that displayed on web page. Users who are not familiar with HTML can also modify the navigation system. The editable configuration file is navigation.txt, which uses more-less Markdown rules. Example:

db=komugai, Komugai
# PHeT Lab
## tags=biologi&db=komugai, Bio
## series=laboratorium biologi&db=komugai, Biologi
## tags=laboratorium&db=komugai, All
# Collections
## db=ebooks&tags=buku pelajaran sma, Pelajaran SMA
## db=tutorial, Tutorials
## db=ebooks, Ebooks
# Shortcuts
## ugai&db=komugai, Ugai
## tags=natural selection&db=komugai, Evolution
tags=about&db=komugai, About

Each time the router boots, it will read and translate this text into HTML format. This structure is easier for lay users to understand than HTML tag-based coding systems. Let's compare with actual HTML after translation below:


   <a class="nav-link" href="?db=komugai">Komugai</a>

    <a class="nav-link dropdown-toggle" href="#" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">PHeT Lab</a>

      <a class="dropdown-item" href="?tags=biologi&amp;db=komugai">Bio</a>
      <a class="dropdown-item" href="?series=laboratorium%20biologi&amp;db=komugai">Biologi</a>
      <a class="dropdown-item" href="?tags=laboratorium&amp;db=komugai">All</a>




    <a class="nav-link dropdown-toggle" href="#" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Collections</a>

      <a class="dropdown-item" href="?db=ebooks&amp;tags=buku%20pelajaran%20sma">Pelajaran SMA</a>
      <a class="dropdown-item" href="?db=tutorial">Tutorials</a>
      <a class="dropdown-item" href="?db=ebooks">Ebooks</a>




    <a class="nav-link dropdown-toggle" href="#" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Shortcuts</a>

      <a class="dropdown-item" href="?ugai&amp;db=komugai">Ugai</a>
      <a class="dropdown-item" href="?tags=natural%20selection&amp;db=komugai">Evolution</a>



   <a class="nav-link" href="?tags=about&amp;db=komugai">About</a>

secured

This blank file set server status. If renamed to .secured, server run in production mode with UUID as parameter, otherwise server run in development mode that display id as integer.

Install

Make sure you have file install.txt inside directory install.

  • Turn on the router with the storage media attached and connect using the command:
telnet 192.168.1.1
  • Continue the setup by typing the mount command and executing the installation script as follows:
mkdir -p /mnt/usb
mount -t vfat /dev/sda1 /mnt/usb 
cd /mnt/usb/ugai/install
sh setup.sh

Done. Next, check for the SSID named Komugai.

Recommended Data Size

  • TP-Link MR3020: Limit to fewer than 1,000 entries, with a maximum of 3 tags per collection.
  • TP-Link MR3420: Limit to fewer than 5,000 entries, with a maximum of 3 tags per collection.
  • TP-Link WR1043ND: Limit to fewer than 10,000 entries, with a maximum of 3 tags per collection.

The Calibre database itself virtualy has no total limit while using ugai.cgi. However, restrictions apply to the total number and logic of items in the navigation menu and the available media storage size.

Example Scenario

Imagine you have a collection of 17,000 educational textbooks in PDF format, officially issued by your country's Ministry of Education as standard text book. You intend to store these on an MR3420 server for high school use. Additionally, you have hundreds of educational videos created by local high school teachers.

Organize Your Collection:

  1. Segment by Reader Level: Since these resources are for a high school, separate any non-high school materials into a different Calibre database.
  2. Manage Excess Volumes: If the collection of high school-appropriate ebooks (or teacher-created videos) exceeds 5,000 items, further divide them by subject (e.g., Physics, Chemistry, Biology, Sociology, Economics, etc.). Calibre it self has excelent tools to do this job easily. This step will be more easier if you already set tags for each item base on subject. Again, Calibre it self has excelent tools to do this job easily.

Your directory will appear as follows:

ugai
├── install
└── www
    └── data
        ├── elementaryschool
        ├── highschool_biology
        ├── highschool_chemistry
        ├── highschool_economy
        ├── highschool_history
        ├── highschool_physics
        ├── komugai
        ├── midschool
        └── references

Next, rewrite navigation.txt as follows using you text editor (Notepad, GEdit, nano, dll)

db=komugai, home
# Text Books
## db=highschool_biology, biology
## db=highschool_chemistry, chemistry
## db=highschool_economy, economy
## db=highschool_history, history
## db=highschool_physics, physics
# Bonuses
## db=midschool, midschool
## db=elementaryschool, elementaryschool
## db=references, references

Plug your USB/HDD into MR3420 and power-on.

Maintenance

Add/Delete/Edit Calibre Data

After making changes to data (such as adding, deleting, renaming, etc. from Calibre), create a blank file named index.txt inside the ugai\install directory, and then return your media to the router. Whenever index.txt is found, the system will generate index files for each database to enhance response times. During this process, the system will be very busy and may not be able to handle any requests. After the index files are generated, the system will reboot, and operations will return to normal.

Upgrade

If you need to upgrade the ugai.cgi file while keeping your customized design, simply download file ugai.cgi from https://github.com/undix/ugai/blob/main/www/ugai.cgi and replace the existing one.

Reinstall

If there are issues with the current version, you can reinstall while preserve your own Calibre data by following these steps:

  • Create a blank text file named reset.txt.
  • Place reset.txt into directory ugai\install.
  • Start the router as usual to reset it. Power off router and put back your USB/SSD/HDD to computer.
  • If you have existing Calibre data, move the data directory and navigation.txt file to a location outside of the ugai directory.
  • Delete or rename the ugai directory.
  • Download the new source code from GitHub.
  • Replace the data directory in the new source with your own Calibre data and also replace navigation.txt inside directory install .
  • Follow the installation instructions as previously described to set up a fresh system with your Calibre data and navigation menu intact.

This process will ensure you have a clean installation while preserving your custom data.

Problem with Calibre Version

The Calibre Desktop Application, starting from version 4, utilizes sqlite3 features that are not supported by the version used in OpenWRT 12.09. Therefore, to avoid any issues when running the "ugai" webapp, please use Calibre Desktop Application version 3.48. To obtain version 3.48 (2019), you need to remove your current Calibre app first and downgrade to 3.48 from Calibre repositori. If you are already have Calibre newer than 3.48 and reluctant to downgrade, you can choose portable edition (Windows 64-bit only).

If you've never used Calibre before, you can find plenty of tutorials on the internet, including on YouTube. For more tailored assistance, consider joining the Calibre community.

Common Error Cases

Page Not Displayed / CGI Error

  • Ensure that all entries in config.json are absolutely correct.

Web Running but Not Displaying Entries from Calibre

  • Double-check config.json to ensure the "server" value is correctly configured.

Cannot Find config.json

  • Enable your file manager to show all hidden files and directories by pressing CTRL+H.
  • Upon boot, the ugai.cgi environment automatically renames config.json to .config.json.

Running Too Slow

  • The more active users there are, the more resources are required, which are already limited (512 MB memory). Consider reducing the number of items in your Calibre database.
  • Create a new Calibre database within the data directory, then move (copy-and-delete) items into this new database based on criteria like subject, format, publisher, authors, pulished date, tags, etc.
  • Remember to register your new database in navigation.txt to display it in the navigation panel.

Incomplete Item

  • A collection will not be displayed if it lacks a cover, comments/description, or file attachment.
  • If you need just a single page (similar to a blog post), use the Calibre feature to add a blank file (TXT).
  • If you don't have cover, use Calibre built-in feature to make cover.

About

Ugai

Imagine ugai.cgi, pronounced ooh-guy, as the brain of a person. Just like your brain helps you think and do your schoolwork, ugai.cgi helps organize all the digital books in a special library called Calibre. It makes sure everything in the library works just right, so you can read and learn without any problems. Ugai.cgi is super important because it keeps the library running smoothly. In the real world, the name ugai refers to a hamlet on Siberut Island in the Mentawai Islands, Indonesia, meaning "home."

Komugai

Now, think of Komugai, pronounced co-mooh-guy, as the body of a person, including the clothes they wear. Imagine you can change your outfits anytime you like. Komugai decides how the online library looks and feels, kind of like how you pick your clothes every day. If you wear different clothes, you're still you, but you might not look like you belong to a specific group, like your school or a sports team, unless you wear their standard outfit. Komugai helps make the library easy to use and nice to look at, just like how your favorite outfit makes you feel good. Under the MIT License, you can change the "clothes" any way you want, as long as you still show the original creator's "brand" on your clothes. In short: ugai is the brain of Komugai 2024. You can keep using "Komugai" for your new "clothes" or pick a totally new name, but one thing is certain: you're still using ugai.cgi and need pay attention about it's upgrade version in the future.

The prefix kom in Komugai stands for communications. The Komugai server is specifically designed to operate in remote areas and can function off-grid without an Internet connection. Equipped with a shoutbox application, Komugai serves as a communication tool for local communities. This feature is extremely valuable, especially during the COVID-19 pandemic, when classrooms in remote areas of Indonesia have been closed.

The term komugai also means 'creatively using available resources to solve problems.' This term is borrowed from the Mee ethnic group in Papua, Indonesia, and it aligns perfectly with the project's environmentally friendly goals.

Perpustakaan Nirkabel

Finally, Perpustakaan Nirkabel, or the Wireless Library Project, is about what you do with this setup after it's installed. Starting from 2014, this project sends educational materials to people in remote places where it's hard to get such resources. It's like going out and helping other people learn new things, using your brain (Ugai) and your body (Komugai) to make a difference. If you use the tools and designs from ugai.cgi and Komugai but are helping out with a different group or in your own community, you're doing great work, but you're not officially part of the Perpustakaan Nirkabel Project.

Also, if you download and use this setup for personal reasons (like learning HTML, JavaScript, jQuery, pentesting, office meeting room, even make personal profit) or just in your school, you're not considered part of the 'Perpustakaan Nirkabel' Project, but you're still a user of both ugai.cgi and Komugai digital wireless server system. Some people call this "social impact."

In short: ugai.cgi is the brain that makes everything work, Komugai is like your whole body and the clothes that make you unique, and Perpustakaan Nirkabel Project is how you use these tools.

Selayang pandang proyek Perpustakaan Nirkabel

Perpustakaan Nirkabel (wireless library) is a 12-year-old project bringing digital technology to remote areas in Indonesia, empowering basic education and bridging the gap in education. It enables students in remote areas to access knowledge and resources previously out of reach. Witness the tech enthusiasts' brainchild with a heart for education.

detail