view release on metacpan or  search on metacpan

doc/webdyne.md  view on Meta::CPAN

    # Net::Server via :
    # cpanm --force Net::Server
    #
    cpanm Task::WebDyne::Starman

you can then 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. If app.psp exists in the directory it will be 
    #  served by default. If it does not exist a file index will be displayed
    #
    $ webdyne.psgi <directory>

    #  E.g serve files in /var/www/html. By default WebDyne will serve app.psp if no filename
    #  is specified. If app.psp does not exist a file index will be displayed.
    #
    $ webdyne.psgi /var/www/html

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

!!! tip

    Starting WebDyne this way will enable "developer" mode such that a
    directory index will be displayed if an app.psp file does not exist, and
    full error messages with code backtraces are displayed if any errors are
    encounterd.

To start with `plackup`:

    #  Start WebDyne via plackup in the current directory. A file named app.psp must exist,
    #  directory indexing will not be performed.
    #
    DOCUMENT_ROOT=. plackup `which webdyne.psgi`

    #  Start serving a single file
    #
    DOCUMENT_ROOT=./time.psp plackup /opt/perl5/bin/webdyne.psgi

    #  Start with some Plack middleware added
    #
    DOCUMENT_ROOT=./time.psp  plackup -e 'enable Plack::Middleware::Debug' `which webdyne.psgi`

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

    Plack (via `webdyne.psgi` or `plackup`) and Starman versions of WebDyne
    serve basic static files such as css, js, jpg etc. If you want more
    control over non PSP files you should us best practices for service such
    files via a traditional web server front end. Also note the Starman and
    plackup instances of WebDyne do not support the --test option or
    indexing - it assumes you are running in a production environment and
    have checked everything with the Plack implementation of `webdyne.psgi`
    first.

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 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](https://github.com/aspeer/WebDyne/pkgs/container/webdyne).
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
    # docker pull ghcr.io/aspeer/webdyne:fedora

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 -v $(pwd):/app:ro -e PORT=5011 -e DOCUMENT_ROOT=/app -p 5011:5011 --name webdyne webdyne:latest

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](https://github.com/aspeer/psp-WebDyne-Fortune):

doc/webdyne.md  view on Meta::CPAN

    #
    <location /shop/>
    PerlHandler     WebDyne
    PerlSetVar      WebDyneHandler               'WebDyne::Chain'
    PerlSetVar      WebDyneChain                 'WebDyne::Session'
    </location>


    #  This is the same, and is more efficient
    #
    <location /shop/>
    PerlHandler     WebDyne::Chain
    PerlSetVar      WebDyneChain                 'WebDyne::Session'
    </location>

# Miscellaneous

## Command Line Utilities

Command line utilities are fairly basic at this stage. Installation
location will vary depening on your distribution - most will default to
`/usr/local/bin`, but may be installed elsewhere in some cases,
especially if you have nominated a `PREFIX` option when using CPAN.

`wdapacheinit`

:   Runs the WebDyne initialization routines, which create needed
    directories, modify and create Apache .conf files etc.

`wdcompile`

:   Usage: `wdcompile filename.psp`. Will compile a PSP file and use
    Data::Dumper to display the WebDyne internal representation of the
    page tree structure. Useful as a troubleshooting tool to see how
    HTML::TreeBuilder has parsed your source file, and to show up any
    misplaced tags etc.

`wdrender`

:   Usage: `wdrender filename.psp`. Will attempt to render the source
    file to screen using WebDyne. Can only do basic tasks - any advanced
    use (such as calls to the Apache request object) will fail.

`wddump`

:   Usage: `wddump filename`. Where filename is a compiled WebDyne
    source file (usually in /var/webdyne/cache). Will dump out the saved
    data structure of the compiled file.

`wddebug`

:   Usage: `wddebug --status|--enable|--disable`. Enable/disable
    debugging in the WebDyne code. This uses some pretty ugly methods to
    enable debugging in already installed modules by editing the code
    on-disk to re-enable debug calls - do not use in a production
    environment !

`webdyne.psgi`

:   Used to run WebDyne as a PSGI process- usually invoked by Plack via
    plackup or starman, but can be run directly for development
    purposes.

`wdlint`

:   Run `perl -c -w` over code in \_\_PERL\_\_ sections on any PSP file
    to check for syntax errors. Will automatically skip HTML code. It
    only checks code in the \_\_PERL\_\_ area, and won't check syntax in
    in-line perl, dynamic attributes etc.

## Other files referenced by WebDyne

`/etc/webdyne.conf.pl, ~/.webdyne.conf.pl, $DOCUMENT_ROOT/.webdyne.conf.pl, $DOCUMENT_ROOT/webdyne.conf.pl`

:   Used for storage of local constants that override WebDyne defaults.
    See the [WebDyne::Constant](#webdyne_constants) section for details

# Extending WebDyne

WebDyne can be extended by the installation and use of supplementary
Perl packages. There are several standard packages that come with the
Webdyne distribution, or you can build your own using one of the
standard packages as a template.

The following gives an overview of the standard packages included in the
distribution, or downloadable as extensions from CPAN.

## WebDyne::Chain {#webdyne_chain}

WebDyne::Chain is a module that will cascade a WebDyne request through
one or more modules before delivery to the WebDyne engine. Most modules
that extend WebDyne rely on WebDyne::Chain to get themselves inserted
into the request lifecycle.

Whilst WebDyne::Chain does not modify content itself, it allows any of
the modules below to intercept the request as if they had been loaded by
the target page directly (i.e., loaded in the \_\_PERL\_\_ section of a
page via the "use" or "require" functions).

Using WebDyne::Chain you can modify the behaviour of WebDyne pages based
on their location. The WebDyne::Template module can be used in such
scenario to wrap all pages in a location with a particular template.
Another would be to make all pages in a particular location static
without loading the WebDyne::Static module in each page:

    <Location /static>

    #  All pages in this location will be generated once only.
    PerlHandler     WebDyne::Chain
    PerlSetVar      WebDyneChain    'WebDyne::Static'

    </Location>

Multiple modules can be chained at once:

    <Location />

    #  We want templating and session cookies for all pages on our site.
    PerlHandler     WebDyne::Chain
    PerlSetVar      WebDyneChain    'WebDyne::Session WebDyne::Template'
    PerlSetVar      WebDyneTemplate '/path/to/template.psp'