|
5 months ago | |
---|---|---|
conf | 11 months ago | |
hunchentoot-example | 11 months ago | |
scripts | 11 months ago | |
src | 5 months ago | |
static | 5 months ago | |
storage/default-assets | 11 months ago | |
templates | 5 months ago | |
tests | 11 months ago | |
.gitignore | 11 months ago | |
LICENSE | 11 months ago | |
README.org | 10 months ago | |
app.lisp | 5 months ago | |
makefile | 11 months ago | |
ritherdon-archive.asd | 11 months ago |
README.org
- Nicola Ellis and Ritherdon Archive
- Overview of Technology Used
- System Overview
- Installation
- Run System on Local Machine
- Run System on (Prod.) Server
- A Note on Using Ritherdon Archive
Nicola Ellis and Ritherdon Archive
This is an website, written in Common Lisp and built on top of the Caveman2 framework. Its main intention is to be the digital archive for the work produced by Nicola Ellis during her time working alongside Ritherdon.
Overview of Technology Used
Below is a non-exhaustive list of the tech. used to build and run this website:
- Common Lisp
- Quicklisp
- http://www.sbcl.org/">http://www.sbcl.org/ (SBCL)
- Caveman2
- woo (Common Lisp server behind Nginx)
- Mito (ORM)
- SXQL (SQL Generator, used alongside Mito)
- SQLite3
- Djula (Common Lisp port of the Django templating language)
- Debian 11
- Nginx
- Meilisearch (Website's Search engine)
For a complete list of packages used by Common Lisp, look at the ritherdon-archive.asd file.
System Overview
The complete system is broken into two services:
- Ritherdon Archive (the main site)
- Meilisearch (the separate search system/service/instance)
From an end-user's perspective, they shouldn't be able to tell the Meilisearch service is part of the overall system. When an end-user uses the Search features on the main site, the main site will make the requests to the Meilisearch service. From there, the Meilisearch service will return its results to the main site – on the end-user's machine. You should see this closed-loop in the diagram below.
graph TD
Request((Request)) --> Server
Server{Nginx} --> Archive
Server -.-> Meilisearch
Archive -. Search terms sent to server \n as their own requests .-> Request
Request -.-> Server
Meilisearch -. Results returned to Archive \n on clients machine .-> Archive
Archive --> Response((Response))
When it comes to the main site (Ritherdon Archive), it stores the archive data
in the /storage
directory and the SQLite3 database. Both are kept
in-sync. by the main site – as part of its feature-set.
graph TD
Request((Request \n /Response)) <--> Server
Server{Nginx} <--> Archive
Archive <-.-> DB[(Database)]
Archive <-.-> Storage[/Files in /storage directory/]
Installation
To see what is being called, please read the makefile. If you are unsure how to set-up an environment for developing in Common Lisp, please use the following link:
- Common Lisp Cook Book: Getting Started
- Meilisearch Doc's (Install Guide)
Otherwise, just use the makefile.
git clone https://git.abbether.net/return-to-ritherdon/ritherdon-archive.git
cd ritherdon-archive
sudo make install
make lisp-install
make quicklisp-add
make search-install # Installs Meilisearch.
Note: The make search-install
command adds the meilisearch
binary to
/usr/bin/
. If you want to uninstall Meilisearch, you will need to delete it
from /usr/bin
. Run sudo rm /usr/bin/meilisearch
, to delete it.
Run System on Local Machine
Because the system consists of two systems running in tandem, you will need to have two terminals open to run them separately – and see the logs for each service.
Meilisearch
Usually, you get this part of the system up and running before you get the main site working – mostly because of the tasks flow easier – but it's not essential to start this service first.
# Make sure meilisearch is added to your /usr/bin/ directory.
meilisearch --no-analytics
If you enter http://localhost:7700
in your browser, you should see the
meilisearch search page. Use ctrl-c
to stop the service.
Main Site (Ritherdon Archive)
To run the main site (Ritherdon Archive), start Steel Bank Common Lisp (SBCL)
by running rlwrap sbcl
in your terminal. When SBCL has finished loading, run
the following,
(ql:quicklisp :ritherdon-archive)
(search:set-filter-attributes) ; Configures the Meilisearch service.
(ritherdon-archive:start :server :woo)
Then go to http://localhost:5000
in your browser.
To stop the program, enter (ritherdon-archive:stop)
in SBCL.
Run System on (Prod.) Server
It is assumed you know how to register a domain name and point it your server
running this website and the Meilisearch instance also. I usually use a
sub-domain of the main site (Ritherdon Archive) for the Meilisearch
instance. For example, https://www.nera.com
is the URL for the main site
making https://search.nera.com
the URL for the Meilisearch instance.
This section builds on the one above (running on local machine). The main difference is getting the system to run on Nginx and as a Systemd service.
The first thing to do is replace the parts which say <INSERT USERNAME HERE>
and <INSERT URL HERE>
in the files in /conf
. Those values are specific to
your deployment environment. At the time of writing, there should be four
files in /conf
. They are:
meilisearch.conf
(the config. file for Nginx)meilisearch.service
(the .service file for Systemd)ritherdon-archive.conf
(the config. file for Nginx)ritherdon-archive.conf
(the .service file for Systemd)
After you have entered your details into the .conf
and .service
files,
you can start to copy the files into their new locations.
Set-Up Meilisearch
# Nginx
sudo cp ~/ritherdon-archive/conf/meilisearch-prod.conf \
/etc/nginx/sites-available/meilisearch-prod.conf
sudo ln -s /etc/nginx/sites-available/meilisearch.conf \
/etc/nginx/sites-enabled/
sudo systemctl restart nginx.service
#Systemd
sudo cp ~/ritherdon-archive/conf/meilisearch.service \
/etc/systemd/system/meilisearch.service
sudo systemctl daemon-reload
sudo systemctl enable meilisearch.service
sudo systemctl status meilisearch.service
Set-Up Ritherdon Archive (Main Site)
# Nginx
sudo cp ~/ritherdon-archive/conf/ritherdon-archive.conf \
/etc/nginx/sites-available/ritherdon-archive.conf
sudo ln -s /etc/nginx/sites-available/ritherdon-archive.conf \
/etc/nginx/sites-enabled/
sudo systemctl restart nginx.service
#Systemd
sudo cp ~/ritherdon-archive/conf/ritherdon-archive.service \
/etc/systemd/system/ritherdon-archive.service
sudo systemctl daemon-reload
sudo systemctl enable ritherdon-archive.service
sudo systemctl status ritherdon-archive.service
After everything is set-up, head over to the site's live URL and complete the set-up form.
Set-up Filter Attributes for Meilisearch Instance
After the search and main site's are set-up, you should be ready to set the
filter attributes used by Meilisearch. The quickest way to do that is to run
the following commands in SBCL (rlwrap sbcl
),
(ql:quickload :ritherdon-archive)
(search:set-filter-attributes)
(exit)
You might need to stop the ritherdon-archive Systemd service sudo systemctl
stop ritherdon-archive.service
to run the above commands. If that is the
case, remember to start the Systemd service, sudo systemctl start
ritherdon-achive.service
.
A Note on Using Ritherdon Archive
This README has focused only on the developer side of the project. This is deliberate. I just haven't had the time to write any documentation on that side of the site or is the budget there to do so. Hopefully, this will change but at the time of writing (Nov. 2022), there is nothing in the repo's wiki.