◈ Artefacts

The Book of Artefacts – also known simply as Artefacts – is the digital version of a commonplace book or a florilegium; that is to say, Artefacts is a web-based application written in Ruby using the Sinatra framework, which aims to be a place where one may save quotes, ideas, poems, or other data in a digital format.

Each piece of data within this digital book is called an artefact, and it is symbolised by ◈. Each artefact can contain various pieces of information about its date of release, its author, the place where it was encountered – its origin – as well as personal notes.

For better organisation, one may add tags to each artefact as well as assign them a general category such as "Poetry" or "Quote". Authors can be assigned to artefacts, and artefacts can be added to sources, too. Thus, if one wishes to group artefacts from a particular book together, one can create a new source – which is the book from which the artefacts have been taken – and assign the source to each artefact originating from this source.

Suggested workflow

The simplest workflow looks as follows.

1. Create a category
2. Create an author
3. Create an artefact and assign both category and author

You are always able to rename or edit any type of data after its creation. Thus, should you wish to rename a category or an author or should you wish to change the category to which an artefact is assigned, you may do so at any time after its initial creation.

Note

In order to create an artefact, you will need to have at minimum created its author first, though we do recommend that you also create and assign a proper category to it right away.

Installation

Please note that Artefacts is still in active development and these instructions may change over time. There are two manners in which you can install Artefacts: via Docker or "bare-metal". We recommend that you use the Docker installation method, especially if you are less experienced or simply wish to have Artefacts up and running in a matter of seconds.

Docker installation

Prerequisites: A proper installation of both docker and docker-compose. Please see Docker's official website for information on how to proceed with the installation for your platform.

Begin by creating a new folder at a location of your choice and title it artefacts. Within the aforementioned folder, create a .env file and fill it with the following content:

CARDS_PER_PAGE=5
BOQ_USER=your_username_here
BOQ_PASSWORD=your_password_here

Please replace the your_username_here and the your_password_here values with your desired credentials. If you do not wish to have authentication enabled, you may append the following line to your .env file: DISABLE_AUTH=true.

Next, you must create a docker-compose.yml file within the same folder and fill it with the following contents:

services:
  artefacts:
    image: codeberg.org/hexaitos/artefacts:latest
    ports:
      - "6660:6660"
    volumes:
      - boq_data:/usr/src/app/db
      - ./.env:/usr/src/app/.env
    restart: unless-stopped

volumes:
  boq_data:

Note

The information in the README may be out of date. Please check the docker-compose_example as well as the .env.example files within this repository for up-to-date information.

Once you have done so, you may run (sudo) docker compose up -d to start the container. Artefacts listens on port 6660 by default.

Docker without docker compose

Prerequisites: A proper installation of docker. Please see Docker's official website for information on how to proceed with the installation for your platform.

Begin by creating a new folder at a location of your choice and title it artefacts. Within the aforementioned folder, create a .env file and fill it with the following content:

CARDS_PER_PAGE=5
BOQ_USER=your_username_here
BOQ_PASSWORD=your_password_here

Please replace the your_username_here and the your_password_here values with your desired credentials. If you do not wish to have authentication enabled, you may append the following line to your .env file: DISABLE_AUTH=true.

Next, create a Docker volume to persist your data and pull the image:

docker volume create boq_data
docker pull codeberg.org/hexaitos/artefacts:latest

Once you have done so, you may start Artefacts with the following command, run from within the artefacts folder:

docker run -d --restart unless-stopped \
  -v boq_data:/usr/src/app/db \
  -v $PWD/.env:/usr/src/app/.env \
  -p 6660:6660 \
  codeberg.org/hexaitos/artefacts:latest

Artefacts listens on port 6660 by default.

Uninstalling

Should you wish to remove Artefacts entirely, you may stop and remove the container, then remove the image and the data volume with the following commands:

docker rm -f $(docker ps -q --filter ancestor=codeberg.org/hexaitos/artefacts:latest)
docker rmi codeberg.org/hexaitos/artefacts:latest
docker volume rm boq_data

Warning

Removing the boq_data volume will permanently delete all of your artefacts. Please ensure that you have exported your database beforehand should you wish to retain your data.

Database Import / Export

The app uses a SQLite database stored inside the container at /usr/src/app/db/boq.db.

Export (container → host)

docker cp $(docker compose ps -q artefacts):/usr/src/app/db/boq.db /path/to/boq.db

Import (host → container)

docker cp /path/to/boq.db $(docker compose ps -q artefacts):/usr/src/app/db/boq.db && docker compose restart artefacts

The restart is necessary for the app to pick up the new database file.

Bare-metal installation

Prerequisites: A recent installation of Ruby 4 and Bundler, as well as git. Please refer to the official Ruby website for instructions on how to install Ruby on your platform.

Begin by cloning the repository into a folder of your choice:

git clone https://codeberg.org/hexaitos/artefacts.git
cd artefacts

Within the aforementioned folder, create a .env file and fill it with the following content:

CARDS_PER_PAGE=5
BOQ_USER=your_username_here
BOQ_PASSWORD=your_password_here

Please replace the your_username_here and the your_password_here values with your desired credentials. If you do not wish to have authentication enabled, you may append the following line to your .env file: DISABLE_AUTH=true.

Next, install the required dependencies:

bundle install

Once you have done so, you may start Artefacts with the following command:

bundle exec ruby server.rb -e production -p 6660 -o 0.0.0.0

Artefacts listens on port 6660 by default. Should you wish to run Artefacts as a background service that starts automatically on boot, we recommend configuring a systemd service unit for your platform.

Note

The database file will be created automatically at db/boq.db upon first launch. Please ensure that this file is included in your backup routine, as it contains all of your artefacts.

Accessing your Artefacts installation

Once you have followed the aforementioned installation steps and have started Artefacts, you can open a browser on the same machine as your installation of Artefacts and should now be able to navigate to it by entering http://localhost:6660 into the address bar.

If you are running Artefacts on a different machine (and assuming that you are using Linux), type ip a or ifconfig – depending on your distribution – into your terminal and find out the IP address (inet addr or simply inet) for your (wireless) LAN. WiFi is typically wlan0 or similar, whereas a physical LAN port is typically eth0. These naming conventions may differ significantly from distribution to distribution, however.

Once you have figured out the other machine's IP address, you can now navigate to your browser and type http://ipaddress:6660 into your browser. Please note that both your machine and the machine which is running Artefacts need to be in the same local area network. Please also note that modern browsers will typically complain when opening an HTTP-only website – that is, a website not secured with an SSL certificate.

Making Artefacts available publicly

Warning

Please note that making your installation of Artefacts public has a few important security and copyright-related implications. Firstly, make sure that you have chosen a secure username and password as outlined in the installation steps; additionally, make sure that you have not accidentally disabled authentication altogether. Lastly, beware that – depending on your jurisdiction – you may not be allowed to reproduce more than a certain amount of words or sentences from a copyrighted material without permission from the copyright holder. We cannot be held liable for any potential copyright-related issues you may face. Use at your own risk.

Let us assume that you have a server or other device which has a public IP and which is currently not hosting anything else – ports 80 and 443 are available and open to the public; let us also assume that you own the domain my-artefacts.com and have entered your servers public IP addresses into your domain registrar so that my-artefacts.com points to the public IP address(es) of your server.

You can, then, simply install Caddy and use the following configuration assuming that you use the default port of 6660:

my-artefacts.com {
	reverse_proxy localhost:6660
	encode zstd gzip
}

Caddy will automatically obtain an SSL certificate for you and in just a few moments, your website should be available under my-artefacts.com and have HTTPS enabled! It also enables (hopefully) decent caching defaults.