Skip to content
This repository has been archived by the owner on Jul 25, 2024. It is now read-only.

Links Examples

Jump to bottom
James Cheney edited this page Aug 17, 2019 · 8 revisions

The following document explains how to set up a constantly running web server with Links examples as one can run individually as explained in Links installation instructions.

Local OPAM install

It is suggested to install OPAM locally, in the space of a dedicated unprivileged user for Links examples such as linksexamples, rather than run the Links example server as a privileged user using the global OPAM configuration. As of OPAM 2.0 this works as follows:

  • download an OPAM binary, such as
wget https://github.com/ocaml/opam/releases/download/2.0.1/opam-2.0.1-x86_64-linux
chmod +x opam-2.0.1-x86_64-linux
  • put the binary in /home/linksexamples/bin and modify .bash_profile so that PATH includes $HOME/bin before other paths
mkdir bin
mv opam-2.0.1-x86_64-linux bin/opam
echo "export PATH=$HOME/bin:$PATH" > .bash_profile
  • install "bubblewrap". This is not a standard package for Ubuntu 16 (xenial) but the existing packages for later Ubuntu versions seem to work:
wget http://security.ubuntu.com/ubuntu/pool/main/b/bubblewrap/bubblewrap_0.2.1-1ubuntu0.1_amd64.deb
sudo dpkg -i bubblewrap_0.2.1-1ubuntu0.1_amd64.deb

Then doing opam init and opam switch install 4.06.0 and following the rest of the standard install instructions should work.

Running the examples manually

All the examples are already included in the Links package under a directory $HOME/.opam/SWITCH_VERSION/share/links/examples. Having moved to that directory, one can run a web server with all the examples (also involving database) by executing a command:

linx -m --config=/custom/config/file -path=examples:examples/games:examples/dictionary examples/webserver/examples.links

We will later configure this to happen automatically (and restart automatically if the process fails) but testing this manually is a good way to make sure everything is working and the Links configuration setup is correct.

Links Configuration File

A custom config file is required to set up the connection to the database. We create a new postgresql user linksexamples who will have access only to databases related to these examples (not to allow them to temper with databases used in TryLinks).

A new config file, /home/arek/links-examples/config looks as follow:

jsliburl=/lib/
jslibdir=/home/linksexamples/.opam/4.06.0/lib/links/js
database_driver=postgresql
database_args=localhost:5432:linksexamples:<examplePassword>
prelude=/home/linksexamples/.opam/4.06.0/lib/links/prelude.links

where jslibdir and prelude may differ depending on where Links has been installed.

Database

The instructions in the Links installation doc describe how to set up a database provided postgresql user is tied to the unix account. As we have a separate user for the examples, one can run a script described below to create a new user linksexamples and databases required for these examples, and then populate them and grant necessary privileges to linksexamples.

Create a script in $HOME/.opam/SWITCH_VERSION/share/links/examples/dbsetup and run it. Assuming postgres is a superuser, the script looks as follow:

#!/bin/bash
psql -U postgres -c "CREATE USER linksexamples WITH LOGIN ENCRYPTED PASSWORD <linksexamples-password>"
for f in `ls *.sql`; do createdb -U postgres ${f%.sql}; done
for f in `ls *.sql`; do psql -U postgres ${f%.sql} < $f; done
for f in `ls *.sql`; do psql -U postgres -c "GRANT ALL ON DATABASE ${f%.sql} TO linksexamples"; done
for f in `ls *.sql`; do psql -U postgres -d ${f%.sql} -c "GRANT ALL ON ALL TABLES IN SCHEMA public TO linksexamples; GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO linksexamples;"; done

You may be asked for the password for a postgres user multiple times depending on the postgresql settings.

Some of the database configurations have schemas only with no data. The (large) SQL dumps are stored here:

https://github.com/links-lang/links-data

For the dictionary and citations examples to work, these database tables should be populated. To do that, clone the repository above and execute all of the *-data-only.sql scripts which will just populate the data assuming the tables have already been created.

Systemd Configuration File

To run the server continuously, systemd was used. Systemd configuration file, links-examples.service, is located in /lib/systemd/system and looks as follows:

[Unit]
Description=Web server with Links examples
After=network.target

[Service]
Type=simple
User=linksexamples
WorkingDirectory=/home/linksexamples/.opam/4.06.0/share/links
ExecStart=/home/linksexamples/.opam/4.06.0/bin/linx -m --config=/home/linksexamples/links-examples/config --path=examples:examples/games:examples/dictionary examples/webserver/examples.links
Restart=on-failure

[Install]
WantedBy=multi-user.target

Load the new configuration with

$ sudo systemctl daemon-reload

and start the service by executing

$ sudo systemctl start links-examples

To make the application start up when the server boots, run

$ sudo systemctl enable links-examples

Optionally, to see the log of the service, run

$ sudo journalctl -u links-examples --since "<time>"

<time> can be a phrase like today or 1 hour ago

Clone this wiki locally