C. Hinsley

29 April 2023

• Create an Ubuntu AWS EC2 instance.
• Set up git to be able to clone repositories if necessary.
• Run this:

sudo apt update
sudo apt install --yes python3-pip

git clone <https://github.com/gerby-project/hello-world.git>
cd hello-world

# 0) make sure dvipng can be found
sudo apt-get update
sudo apt install --yes dvipng

# 1) install plasTeX
git clone <https://github.com/gerby-project/plastex.git>
cd plastex

# use the Gerby branch of plasTeX
git checkout gerby

# actual install
#python3 setup.py install --user
python3 -m pip install .
cd ..

# 2) fix collections.Callable naming discrepancy with Python 3.10+
# Courtesy <https://stackoverflow.com/a/70641487>
sed -i '8i\\collections.Callable = collections.abc.Callable' ~/.local/lib/python3.10/site-packages/plasTeX/ConfigManager/Generic.py

# 3) install Gerby
git clone <https://github.com/gerby-project/gerby-website.git>
cd gerby-website/gerby/static

# import jQuery Bonsai
git clone <https://github.com/aexmachina/jquery-bonsai>
cp jquery-bonsai/jquery.bonsai.css css/

# actual install
cd ../..
pip install -e . # we use -e because we want to change the source files
cd ..

# 4) setup configuration
mv configuration.py gerby-website/gerby/configuration.py

# 5) setup soft links for plasTeX output
cd gerby-website/gerby/tools
ln -s ../../../document document
ln -s ../../../document.paux document.paux
ln -s ../../../tags tags
cd ../../..

# 6) setup soft links for database
cd gerby-website
ln -s gerby/tools/hello-world.sqlite hello-world.sqlite
ln -s gerby/tools/comments.sqlite comments.sqlite

# 7) other fixes...
sudo apt-get install --yes python3-unidecode
sudo apt-get install --yes texlive-latex-recommended

• Once you’ve written some content and want to update the website:

# 1) fix PATH issue
dir_to_add="/home/ubuntu/.local/bin"
if [[ ! $path_list =~ (^|[:])$dir_to_add($|[:]) ]]; then
    export PATH="$dir_to_add:$PATH"
fi

# 2) update tags file with new tags
cd ..
python3 tagger.py >> tags

# in real life: first run it without writing it to the tags file to check for errors

# 3) convert to HTML: output goes to document/
plastex --renderer=Gerby ./document.tex

# 4) import plasTeX output into database
cd gerby-website/gerby/tools
python3 update.py
cd ../..

• To start the server up the way the devs suggest:

export FLASK_APP=gerby
python3 -m flask run --host=0.0.0.0 &

# testing the setup
sleep 1
wget <http://127.0.0.1:5000/tag/0001>
cat 0001

• However, I prefer to start it up in tmux. Run sudo apt-get install tmux then tmux and, in the tmux console window, run this:

export FLASK_APP=gerby
python3 -m flask run --host=0.0.0.0

• Then, press ctrl-b followed by d to detach from the tmux session. It will stay running when you exit the shell, and you can re-attach to it with tmux a -t 0 later. See https://github.com/tmux/tmux/wiki for more tmux usage information.
• Make sure when you run the server that your working directory is hello-world/gerby-website. Otherwise a new database will be created and you’ll get errors; the website won’t appear when you try to access it.
• Run nano [render.sh](<http://render.sh>) and place into the file this content and save:

python3 -m pip install -e /home/ubuntu/hello-world/gerby-website/

# 1) update tags file with new tags
python3 tagger.py >> tags

# in real life: first run it without writing it to the tags file to check for errors

# 2) convert to HTML: output goes to document/
plastex --renderer=Gerby ./document.tex

# 3) import plasTeX output into database
cd gerby-website/gerby/tools
python3 update.py
cd ../../..

• Run chmod +x render.sh.
• You can run render.sh whenever you want, including while the site is running. This updates renders of tex documents and tags, but you still have to restart the Flask server any time you make an edit. You can also set up a cronjob for these tasks if you want them to automatically run periodically.
• Make sure to set up port 5000 as an exposed incoming TCP port — otherwise you won’t be able to connect to your EC2 instance and see the Gerby website. You can of course change this to any other port. Exposing port 5000 can be done in Security Groups in AWS.