This is the README file for the bedrock project. This page is mostly
geared toward maintainers. If all you want to do is install Bedrock
visit Bedrock's DarkPAN repository or
download an image from
DockerHub.
- See the NEWS file for changes and updates to Bedrock
| Documentation | Description |
|---|---|
| README.md | Overview of Bedrock and this repository |
| README-CI.md | Info on the GitHub Actions build system |
| README-Apache.md | Info on running Bedrock as an Apache application |
| README-LOGS.md | Guide to Bedrock logging |
- Download Bedrock the DarkPAN repository.
- Bedrock images are now available on dockerhub. Try Bedrock now!
Bedrock::Lite- all the flavor, 1/3 less calories- A version of Bedrock without Apache. Useful for basic templating and daemons that need some of Bedrock's goodies.
Bedrock is a server side web development framework that can be used with Apache (and probably other web servers). It allows fullstack web developers to create dynamic web pages through the use of a small set of HTML-like tags that implement a robust templating system. Bedrock is an enabling technology that glues together HTML pages and dynamic data (HTML form data, data from databases, and system services) to create web applications.
Developers can extend Bedrock in interesting ways through the use of Perl plugins.
Bedrock differs significantly from most web application development environments that either generate HTML pages as output (e.g. CGIs, Servlets) or are themselves programs embedded within HTML pages (e.g. PHP, Mason, ASP, etc). By allowing the developer to assemble pages from object oriented components, Bedrock allows front-end web developers and back-end developers to collaborate effectively using familiar, well documented interfaces.
Although Bedrock has grown to include many features, some of which are not found in other web application environments, some interesting and robust applications can be built with only 7 Bedrock tags and the built-in objects $input, $header, $session, and $config:
<if>
<null>
<var>
<sqlselect>
<sql>
<sqlconnect>
<foreach>
Bedrock is under constant development as it serves as the engine that powers Treasurer's Briefcase
Note that if all you want to do is try Bedrock
Bedrock can also be run in a shell as a templating engine.
echo '<trace --output $env>' | bedrock
echo 'Bedrock says <var $input.text>' | bedrock text='Hello World!'
Presumably you are installing Bedrock to do some web application development on an Apache server. There are three basic ways to install Bedrock to enable Bedrock on your Apache server.
First, clone the repo and make sure you have installed all of the necessary prerequistes.
git clone https://github.com/rlauer6/openbedrock.git
The configure script generated by autoconf will check to see if
you have the necessary prerequisites before the build is started.
See the Prerequisites section below for a listing of resources that must be installed and configured on your system before you can install the Bedrock package.
Caveat Emptor: Bedrock is under constant development so the list of required Perl modules that
configurewill look for may not be complete.
Run ./configure --help in the project directory to see the options
available.
Presumably you are installing Bedrock to create a web application that will run on an Apache server. There are three basic ways to enable Bedrock on your Apache server. Here's a generalized description of these methods:
- The standard
autoconfrecipe:./bootstrap ./configure make && make install - From a CPAN distribution tarball
./bootstrap ./configure make cd cpan make cpan sudo cpanm -v Bedrock-3.3.6.tar.gz - From RPM packages
./bootstrap ./configure make dist rpmbuild -tb bedrock-3.3.6.tar.gz rpm -ivh $RPMROOT/RPMS/noarch/bedrock-openbedrock-3.3.6-0.noarch.rpm
Installing Bedrock using the standard
autoconfrecipe will not install things in quite the same way the CPAN distribution tarball method will.
git clone https://github.com/rlauer6/openbedrock.git
cd openbedrock
./bootstrap
./configure --prefix=/usr
make && sudo make install
bedrock --version
Bedrock is not and may never be, uploaded to CPAN. However installling from a distribution tarball s now the preferred way of installing Bedrock. Vist Bedrock's DarkPAN to download the latest tarball.
Installing Bedrock using the tarball installs all of the necessary
components to enable Bedrock on your Apache server. To finalize the
installation you must run the bedrock-site-install script. See man bedrock-site-install.pl for more information about what that script
does how to customize it for your site.
In addition to the prerequistes for manually installing Bedrock you will also need some of the artifacts listed below for building the CPAN tarball and Docker images. Bedrock is under constant development so you might want to look at the Dockerfiles for your particular environment to see all of the necessary libaries and artifacts required.
| Distribition | Dockerfile |
|---|---|
| Amazon Linux | Dockerfile.bedrock-al2023-base |
| Debian | Dockerfile.bedrock-debian-base |
| Fedora | Dockerfile.bedrock-fedora-base |
Other Prerequisites
cpanminusCPAN::Maker- Apache
mod_perl- MySQL
- client libraries
DBD::mysql
- ...and other Perl modules specified in Bedrock's CPAN distribution
Follow the instructions below to create a distribution tarball.
./bootstrap
./configure --prefix=/usr
cd cpan
make cpan
After running the above recipe you should have a tarball in the cpan
directory.
tar xfvz Bedrock-*.tar.gz
cd Bedrock-*.tar.gz
perl Makefile.PL
make && make install
or
cpanm -v Bedrock*.tar.gz
rpm builds are likely not working properly at the moment. Current efforts have been directed at creating a CPAN distribution and Docker images. This functionality may be revisited in the future. The major problem with an rpm build is that Perl has become so out of vogue with the kids that essential rpm packages cannot be found in any yum repository. That leaves you with two options if you want to build your applications using rpms (neither of which are very satisfying).
- Build your required rpms on your own...which I had been doing for a LONG time.
- Package the rpm in such a way that it ignores dependencies and essentially becomes, for all intents and purposes a CPAN tarball.
The manual installation method assumes you are trying to install all
of the components of Bedrock in order to create a web application
using an Apache server. However, rather than directly installing these
components in your web directories, the installation process stages
the components in the directory you configured as datadir under the
/bedrock subdirectory. So if you did this:
./configure --prefix=/usr
You will find all of the components necessary for running a Bedrock
enabled web server under /usr/share/bedrock.
Installing Bedrock from the CPAN distribution will install Bedrock
where you would expect them to be installed using a CPAN installation
method. After installing Bedrock from the CPAN distribution you can
use all of the Perl modules in Bedrock for templating or use the
command line version of Bedrock (bedrock).
echo '<trace --output $config>' | bedrock
Whether you manually install Bedrock or use the CPAN distribution the additional files that make up the web framework are installed are not automatically installed into your web application hierarchy.
A separate utility (bedrock-site-install) is included for
configuring and finalizing your web environment. You typically would
run this utility after after installing Bedrock. The utility takes an
argument that indicates the type of your system (Redhat vs Debian) so
it will install components into the correct locations for that
distribution.
See man bedrock-site-install for more details.
There are many good templating modules (e.g. Template::Toolkit,
Mason, HTML::Template) that are well supported by the Perl
community. Newer web application frameworks like Mojolicious are
rapidly replacing the use of templating packages alone as a web development
framework. Bedrock was born in the late 90's when other solutions
were being born as well. It was used (and is still used today) by the
company that funded its development.
Bedrock has been proven to be extremely useful for prototyping, rapid application development and anything that needs a solid templating enviroment. Give it a try! Feedback welcome!
Bedrock includes a comprehensive set of tests that exercise the tags
as well as the Perl modules that implement Bedrock. Bedrock uses
Test::More and its own testing framework. To run the full suite of
tests requires a MySQL server being available. If no server is
available those tests that require MySQL will be skipped.
See the README files is the perl and
perl/lib directories for more
information on testing Bedrock.
You can build a Docker image and try Bedrock in a local
environment. See the README file in the docker directory for more
information about build a Docker image for different distros.
- See the
NEWSfile for changes for this release, and a running list of changes from previous releases. Any incompatibilities with previous versions will be noted in the 'NEWS' file.
Bedrock is intended to be built on Unix and Unix-like systems, so expects a standard set of utilities (cat, sed, awk, rm, ...) to be present. These utilities are not explicitly listed below as prerequisites as they should be present on any modern Unix or GNU/Linux system (or Cygwin, if the Universe hates you ;-). We also do not explicitly list those Perl modules that are part of the core library shipped with Perl (e.g., Data::Dumper, MIME::Base64, etc.)
The various Bedrock components are primarily implemented in Perl, so of course, a Perl installation is needed. Current Bedrock development is done using Perl 5.16, but any 5.10.x+ features that are used should be conditional. This means that Bedrock should work with versions of Perl prior to 5.16 as well.
Here's a list (not guaranteed to be complete) of the packages you may need to install:
automakeautoconfapache2make
Ubuntu support via Debian packages will likely never happen, however Bedrock will run on Ubuntu using the manual installation method or as a CPAN distribution.
At one time a Debian package was available for Bedrock, however the
packaging scripts have gone out of maintenance. Using Debiain packages
is likely to run into the same limitations as using rpms - a dirth of
necessary modules (although there do seem to be more people creating
.deb versions of Perl modules).
Volunteers welcome! Take a look at the setup-ubuntu.sh script as a
starting point.
Perl module dependencies are listed in the configure.ac file. Some
are marked as optional although you may need to have them installed to
build the distribution. While you may be able to load these modules
from Debian repositories, using cpanm
https://metacpan.org/pod/App::cpanminus is
preferable as it will get you the latest version of these modules.
After satisfying dependencies, build and install Bedrock in the standard Unix way:
$ ./configure --prefix=/usr
$ make
$ sudo make install
- Bedrock running as a CGI should work with no compatibility issues under Apache 1.x/2.x+
- For increased performance use
mod_perlwith Apache 2.2/2.4.
Bedrock implements persistent user sessions using an application plugin called BLM::Startup::UserSession. The reference implementation installed by Bedrock uses a MySQL database to persist user data.
There are also implementations using PostgreSQL, SQLite and even Redis.
To create the database and table necessary to use the Bedrock $session
object, you'll want to do something similar to:
$ cat /usr/share/bedrock/create-session.sql | mysql -u root -p bedrock
- See
perldoc BLM::Startup::UserSessionfor more details.