Racket Package Library Website

Prerequisites

You will need to install the following Racket packages:

raco pkg install reloadable

Configuration

See the directory configs/ for example configuration files. To select a configuration file, set the environment variable CONFIG to its base filename. For example, to select configs/live.rkt, set CONFIG to live. A good place to do this is in the run-prelude file; see the description of run-prelude below.

If CONFIG is not set, it defaults to the short hostname of the machine (hostname -s).

Within a configuration file, configuration details are to be given as a hashtable to main.

Keys useful for deployment:

• port: number; default the value of the SITE_PORT environment variable, if defined; otherwise, 8443.
• ssl?: boolean; default #t.
• reloadable?: boolean; #t if the SITE_RELOADABLE environment variable is defined; otherwise, #f.
• recent-seconds: number, in seconds; default 172800. Packages modified fewer than this many seconds ago are considered "recent", and displayed as such in the UI.

Keys useful for development:

• package-index-url: string; default http://pkgs.racket-lang.org/pkgs-all.json.gz.
• package-fetch-interval; number, in seconds; default 300.
• session-lifetime: number, in seconds; default 604800.
• static-generated-directory: string; names a directory relative to src/ within which generated static HTML files are to be placed. Must be writable by the user running the server.
• static-urlprefix: string; absolute or relative URL, prepended to relative URLs referring to static HTML files placed in static-generated-directory.
• dynamic-urlprefix: string; absolute or relative URL, prepended to URLs targetting dynamic content on the site.
• disable-cache?: boolean; default #f.
• backend-baseurl: string; default https://pkgd.racket-lang.org. Must point to the backend package server API root, such that (for example) /jsonp/authenticate, when appended to it, resolves to the authentication call.
• pkg-build-baseurl: string; default http://pkg-build.racket-lang.org/. Used to build URLs relative to the package build host, for such as documentation links and build reports.

Local testing

You will need some dummy SSL keys. Run make keys to produce some.

Running src/main.rkt starts a local server. For your convenience,

make compile run

compiles the code and starts the server.

Automatic code reloading

If you would like to enable the automatic code-reloading feature, set the environment variable SITE_RELOADABLE to a non-empty string or set the reloadable? configuration variable to #t.

You must also delete any compiled code .zo files. Otherwise, the system will not be able to correctly replace modules while running.

Therefore, when using automatic code reloading, use just

make run

and make sure to run make clean beforehand, if you've run make compile at all previously.

Deployment

Supervision

Startable using djb's daemontools; symlink this directory into your services directory and start it as usual. The run script starts the program, and log/run sets up logging of stdout/stderr.

If the file run-prelude exists in the same directory as run, it will be dotted in before racket is invoked. I use this to update my PATH to include my locally-built racket bin directory, necessary because I don't have a system-wide racket, and to select an appropriate CONFIG setting.

On Debian, daemontools can be installed with apt-get install daemontools daemontools-run, and the services directory is /etc/service/.

Control signals

You can send signals to the running service by creating files in /etc/service/webservice/signals/. For example:

• creating .pull-required causes the server to shell out to git pull and then exit. Daemontools will restart it.

• creating .restart-required causes it to exit, to be restarted by daemontools.

• creating .reload causes an explicit code reload. Useful when automatic code reloading is disabled.

• creating .fetchindex causes an immediate refetch of the package index from the backend server.

• creating .rerender causes an immediate rerendering of all generated static HTML files.

See src/signals.rkt for details of the available signals.

So long as sudo chmod 0777 /etc/service/webservice/signals, these are useful for non-root administrators to control the running service.

In particular, a git post-receive hook can be used to create the .pull-required signal in order to update the service on git push.

Copyright and License

Copyright © 2014 Tony Garnock-Jones

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.