Installation and Quickstart

Prerequisites

WebDyne will install and run on any modern Linux system that has a recent version of Perl installed and is capable of installing Perl module via CPAN. Installation via Docker is also supported.

When installing WebDyne there are two components which are required before you can begin serving .psp files:

• The core WebDyne Perl modules

• A web server configured to use WebDyne

WebDyne will work with Apache mod_perl or PSGI compatible web servers (such as Plack, Starman etc.).

Docker containers with pre-built versions of WebDyne are also available.

Installing via CPAN or CPANMinus

Install from the Perl CPAN library using cpan or cpanm utilities. Installs dependencies if required (also from CPAN).

Destination of the installed files is dependent on the local CPAN configuration, however in most cases it will be to the Perl site library location. WebDyne supports installation to an alternate location using the PREFIX option in CPAN. Binaries are usually installed to /usr/bin or /usr/local/bin by CPAN, but may vary by distribution/local configuration.

Assuming your CPAN environment is setup correctly you can run the command:

perl -MCPAN -e "install WebDyne"

Or (with cpanminus if installed)

cpanm WebDyne

This will install the base WebDyne modules, which includes the Apache config utility and PSGI version. Note that Apache or PSGI servers and dependencies such as Plack or Starman are not installed by default and need to be installed separately - see the relevant section.

Once installed you will need to configure your web server to use WebDyne to serve files with the .psp extension if using Apache - see section below.

Quickstart

If using PSGI you can start a quick web server with:

#  Render a file to STDOUT to see the HTML
#
$ wdrender app.psp

#  Install Plack
#
$ cpanm Plack

#  Check all working
#
$ webdyne.psgi --test

#  Start serving only a single PSP file
#
$ webdyne.psgi app.psp

# Start serving any file in the current directory, using app.psp as the default
#
$ webdyne.psgi .

# Start but listen on non-default port, only on localhost
#
$ webdyne.psgi --port=5001 --host=127.0.0.1

Connect your browser to the host and you should see the WebDyne output

Apache mod_perl

If using Apache with mod_perl you can initialise WebDyne using the wdapacheinit command. This will attempt to auto-discover where the Apache binary and configuration files are, then add a suitable webdyne.conf file to the apache configuration. Apache will need to be restarted for the new configuration file to take effect. This will need to be done as a the root user.

[root@localhost ~]# wdapacheinit 

[install] - Installation source directory '/usr'.
[install] - Creating cache directory '/var/cache/webdyne'.

[install] - Writing Apache config file '/etc/httpd/conf.d/webdyne.conf'.
[install] - Writing Webdyne config file '/etc/httpd/conf.d/webdyne_conf.pl'.
[install] - Apache uses conf.d directory - not changing httpd.conf file.
[install] - Granting Apache (apache.apache) ownership of cache directory '/var/cache/webdyne'.
[install] - Install completed.

[root@localhost ~]# systemctl restart httpd

By default WebDyne will create a cache directory in /var/cache/webdyne on Linux systems when a default CPAN install is done (no PREFIX specified). If a PREFIX is specified the cache directory will be created as $PREFIX/cache. Use the wdapacheinit --cache command-line option to specify an alternate location.

Once wdapacheinit has been run the Apache server should be reloaded or restarted. Use a method appropriate for your Linux distribution.

[root@localhost ~]# systemctl httpd restart
Stopping httpd:                                            [  OK  ]
Starting httpd:                                            [  OK  ]

Manual configuration of Apache

If the wdapacheinit command does not work as expected on your system then the Apache config files can be modified manually.

Include the following section in the Apache httpd.conf file (or create a webdyne.conf file if you distribution supports conf.d style configuration files). These following config files are written with Apache 2.4 syntax - adjust path and syntax as required:

#  Need mod_perl, load up if not already done
#
<IfModule !mod_perl.c>
LoadModule perl_module "/etc/httpd/modules/mod_perl.so"
</IfModule>

#  Uncomment and update if using a local::lib location for Perl modules
#
#PerlSwitches -I/opt/perl -I/opt/otherperl

#  Preload the WebDyne and WebDyne::Compile module
#
PerlModule    WebDyne WebDyne::Compile

#  Associate psp files with WebDyne
#
AddHandler    modperl    .psp
PerlHandler   WebDyne

#  Set a directory for storage of cache files. Make sure this exists already is writable by the 
#  Apache daemon process.
#
PerlSetVar    WEBDYNE_CACHE_DN    '/opt/webdyne/cache'

#  Allow Apache to access the cache directory if it needs to serve pre-compiled pages from there.
#
<Directory "/opt/webdyne/cache">
Require all granted
</Directory>

# Put variables in a separate file - best
#
PerlRequire conf.d/webdyne_constant.pl

#  Or use <Perl> sections - but warning, certbot doesn't like this syntax in http conf files
#
<Perl>

#  Error display/extended display on/off. Set to 1 to enable, 0 to disable
#
$WebDyne::WEBDYNE_ERROR_SHOW=1;
$WebDyne::WEBDYNE_ERROR_SHOW_EXTENDED=1;
</Perl>

Important

Substitute directory paths in the above example for the relevant/correct/appropriate ones on your system.

Create the cache directory and assign ownership and permission appropriate for your distribution (group name will vary by distribution - locate the correct one for your distribution)

[root@localhost ~]# mkdir /opt/webdyne/cache
[root@localhost ~]# chgrp apache /opt/webdyne/cache
[root@localhost ~]# chmod 770 /opt/webdyne/cache

Restart Apache and check for any errors.

PSGI

Ensure that Plack is installed on your system via CPAN:

# Via CPAN
perl -MCPAN -e 'install Plack'

# Modern systems
#
cpan Plack

# Or better via CPANM
cpanm Plack

You can start a basic WebDyne server by running the webdyne.psgi command with the --test parameter

webdyne.psgi --test

This will start a PSGI web server on your machine listening to port 5000 (or port 5001 on a Mac). Open a connection to http://127.0.0.1:5000/ or the IP address of your server in your web browser to view the test page and validate the WebDyne is working correctly:

Once verified as working correctly you can serve WebDyne content from a particular directory - or from a single file - using the syntax:

#  To serve up all files in a directory:
#
$ webdyne.psgi <directory>

#  E.g serve files in /var/www/html. By default WebDyne will serve app.psp if no filename
#  is specified
#
$ webdyne.psgi /var/www/html

#  Allow static files such as css, jpg files etc. to be served also
#
$ webdyne.psgi --static /var/www/html/app.psp

#  Or just a single app.psp file. Only this file will be served regardless of URL
#
$ webdyne.psgi /var/www/html/time.psp

The above starts a single-threaded web server using Plack. To start the more performant Starman server (assuming installed):

#  Start Starman instance. Substitute port + document root and location of webdyne.psgi
#  as appropriate for your system.
#
$ DOCUMENT_ROOT=/var/www/html starman --port 5001 /usr/local/bin/webdyne.psgi

Note

Starman does not support options such as --test and --static. If you want to server static files from starman you should do so using best practice via a traditional web server front end.

Numerous options can be set from the command line via environment variables, including Webdyne configuration. See relevant section for all WebDyne configuration options but assuming in a local file webdyne.conf.pl:

#  Start instance webdyne.psgi using local config file
#
$ WEBDYNE_CONF=./webdyne.conf.pl webdyne.psgi --port=5012 .

Docker

Docker containers are available from the Github Container Registry. Install the default Docker container (based on Debian) via:

#  Default debian version
#
$ docker pull ghcr.io/aspeer/webdyne:latest

#  Or Alpine/Fedora/Perl versions
#
# docker pull ghcr.io/aspeer/webdyne-alpine:latest
# docker pull ghcr.io/aspeer/webdyne-fedora:latest
# docker pull ghcr.io/aspeer/webdyne-perl:latest

Start the docker container with the command:

$ docker run -e PORT=5002 -p 5002:5002 --name=webdyne webdyne

This will start WebDyne running on port 5002 on the host. Connecting to that location should show the server localtime test page

To mount a local page and serve it through the docker container use the command:

docker run --mount <local_dir>:/app:ro -e PORT=5011 -e DOCUMENT_ROOT=/app -p 5011:5011 --name=webdyne webdyne

This will tell docker to mount the local directory into the docker container. If there is a default file named app.psp in the location it will be displayed. if there is a cpanfile in the mount directory any modules will be installed into the docker container automatically.

Deploying WebDyne apps with Docker

The WebDyne container can be used as the basis for new docker images containing your application files. Consider the following directory structure (available from Github as aspeer/psp-WebDyne-Fortune:

psp-WebDyne-Fortune/
├── app.pm
├── app.psp
├── cpanfile
├── Dockerfile
└── webdyne.conf.pl

Where:

app.psp

The main and default psp file

app.pm

Perl code used in the psp file

cpanfile

A list of Perl modules to be installed in the docker container by cpanm

Dockerfile

The docker build file

webdyne.conf.pl

Any variables to be set for the WebDyne environment

Constitute all the files needed to stand up a WebDyne based application in a Docker container. The contents of the Dockerfile are minimal:

FROM webdyne:latest
WORKDIR /app
# Debian packages needed for this app
RUN apt-get update && apt-get -y install fortunes
COPY app.* .
COPY cpanfile .
COPY webdyne.conf.pl /etc

Build the Docker container:

docker build  -t webdyne-app-fortune -f ./Dockerfile .

And run it:

docker run -e PORT=5010 -p 5010:5010 --name=webdyne-app-fortune webdyne-app-fortune

Your application should now be available: