ocular logo

ocular

A tiny offline image feed generator written in Lua.

ocular is a command line tool that lets you add images from your harddrive to create a static website and automatically upload it to your webserver.

Unlike traditional gallery systems, images are added one by one to build a feed of images, similar to how you would use an image sharing platform like Inst*gram or Pixelfed. You can think of it as a minimal indieweb alternative to those platforms — one that keeps you in ownership and control of your data.

There are no social features to speak of, but ocular can optionally post new images to Mastodon to share and comment.

Following other feeds is indirectly possible through the ocular webring.Following other feeds is indirectly possible through the ocular webring. The webring takes all ocular feeds and aggregates them to one chronological gallery.

Ocular is directly inspired by IMGRAM MINI and the subversive.pics webring, which also aggregates the ocular webring galleries.

ocular was written on Ubuntu 22.04.3 LTS. It has not been tested on other platforms. Please get in touch if you are interested in porting it.

Usage

Images reside on your hard drive at any location — ocular will store their path and automatically create smaller sizes geared towards low bandwith usage.

Use ocular -a relative/path/to/your/image.jpg to add an image. ocular will prompt you for a title, a caption, an alt description and keywords. Keywords are used to create a list of tags for filtering the images.

You can always edit all entries and keywords in the json database using ocular -e.

ocular -b builds the static html pages as well as an rss feed containing all entries.

ocular -d deploys the generated content to the webserver. During this process, ocular pulls the rss feeds from the webring and aggregate their images to webring.html. This can also be manually triggered using ocular -w.

For further commands, use ocular -h:

USAGE: ocular [options] [filename]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Options:
-h, help show this help
-a, add add an image
-A, add-deploy add an image and deploy
-b, build build locally
-c, configure show this help
-d, deploy update, build and upload to the webserver
-e, edit edit the database
-o, open open image gallery in the browser
-p, rebuild rebuild previews
-r, remove remove an image
-w, webring update webring
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

ocular preview

Setup

Clone this repository to a local directory of your choice. Create a symlink of the script file ocular in ~/.local/bin/ - or any other directory of you $PATH environment variable. This will make the command ocular available from any location in the terminal.
To see which directories are included in the $PATH variable, execute echo $PATH.

To configure ocular, run ocular -c. It will create a file called config.lua in the src directory that you can edit. This is the place where you need to add your webserver address, so ocular knows where to upload things. To automate uploading, you will need an ssh access to your webserver

If you lack a particular setting after updating, please check the top of src/main.lua for all settings and copy the missing one to your config file.

Building ocular will copy the media/ directory from src/ to dst/. If dst/ doesn't exist, ocular will create it.
When uploading the gallery, ocular will take the content of the dst/ directory and upload it to the webserver.

Posting to Mastodon

ocular can post images to Mastodon only during the process of uploading the gallery to the webserver.
If you add multiple images locally only, ocular can only upload the last image added.

To enable Mastodon uploads, you need to add two environment variables to your .bashrc file:

export MASTODON_ACCESS_TOKEN="insertyouraccesstokenhere"
export MASTODON_INSTANCE="https://instancename" <-- make sure there is no / at the end

To aquire an access token, login on Mastodon, go to Settings > Development and click on new application. Enter the name (e.g. ocular) and the gallery url.
Only select the scopes write:media and write:statuses and press Submit.
When you click on the application, you will see the client key, secret and access token. Do not share them with anyone.

With this in place, ocular will automatically enable Mastodon uploads, but will always prompt you before doing so.

Dependencies

To use this script you need to have Lua and imagemagick command line tools installed.
It requires the dkjson package to read and write JSON. It uses rsync to upload the files to a webserver. Also it uses coreutils such as wget, curl, rm, mkdir, cp, realpath and readlink.

To-Do's

• Use system default text editor instead of command line prompt for keywords and captions
• Prompt before writing everything to the database

Webring

If you use ocular or maintain another gallery with an rss feed, you can join the oculare webring by creating a pull request in it's repository.

Live Preview

You can find a live preview of ocular here: https://ocular.nchrs.xyz

License

See the License file for license rights and limitations (MIT).