vely:Example: form

Example: form

This application is a guest tracking database. The user can:

input first and last name, which once submitted, are added to a database table,
display web page showing the list of names queried from the database.

In a nutshell: PostgreSQL; web browser; Apache; Unix sockets; 4 source files, 86 lines of code.

Screenshots of application

Users can sign the guest book via HTML form:

When a Submit button is clicked, entered data is added to the guest book:

This shows the entire guest book:

Setup prerequisites

Install Vely - you can use standard packaging tools such as apt, dnf, pacman or zypper.

Because they are used in this example, you will need to install Apache as a web server and PostgreSQL as a database.

After installing Vely, turn on syntax highlighting in vim if you're using it:

vv -m

Get the source code

The source code is a part of Vely installation. It is a good idea to create a separate source code directory for each application (and you can name it whatever you like). In this case, unpacking the source code will do that for you:

tar xvf $(vv -o)/examples/form.tar.gz
cd form

Setup application

The very first step is to create an application. The application will be named "form", but you can name it anything (if you do that, change it everywhere). It's simple to do with vf:

sudo vf -i -u $(whoami) form

This will create a new application home (which is "/var/lib/vv/form") and do the application setup for you. Mostly that means create various subdirectories in the home folder, and assign them privileges. In this case only current user (or the result of "whoami" Linux command) will own those directories with 0700 privileges; it means a secure setup.

Setup the database

Before any coding, you need some place to store the information used by the application. First, you will create PostgreSQL database "db_form". You can change the database name, but remember to change it everywhere here. And then, you will create database objects in the database.

Note the example here uses peer-authentication, which is the default on all modern PostgreSQL installations - this means the database user name is the same as the Operating System user name.

Execute the following in PostgreSQL database as root (using psql utility):

echo "create user $(whoami);
create database db_form with owner=$(whoami);
grant all on database db_form to $(whoami);
\q
" | sudo -u postgres psql

Next, login to database db_form and create the database objects for the application:

psql -d db_form -f setup.sql

Connect Vely to a database

In order to let Vely know where your database is and how to log into it, you will create database_config_file named "db_form". This name doesn't have to be "db_form", rather it can be anything - this is the name used in actual database statements in source code (like run-query), so if you change it, make sure you change it everywhere. Create it:

echo "user=$(whoami) dbname=db_form"  > db_form

The above is a standard postgres connection string that describes the login to the database you created. Since Vely uses native PostgreSQL connectivity, you can specify any connection string that your database lets you.

Build application

Use vv utility to make the application:

vv -q --db=postgres:db_form

Note usage of --db option to specify PostgreSQL database and the database configuration file name.

Start your application server

To start the application server for your web application use vf FastCGI process manager. The application server will use a Unix socket to communicate with the web server (i.e. a reverse-proxy):

vf -w 3 form

This will start 3 daemon processes to serve the incoming requests. You can also start an adaptive server that will increase the number of processes to serve more requests, and gradually reduce the number of processes when they're not needed:

vf form

See vf for more options to help you achieve best performance.

If you want to stop your application server:

vf -m quit form

Setup web server

This shows how to connect your application listening on a Unix socket (started with vf) to Apache web server.

- Step 1:
To setup Apache as a reverse proxy and connect your application to it, you need to enable FastCGI proxy support, which generally means "proxy" and "proxy_fcgi" modules - this is done only once:

For Debian (like Ubuntu) and OpenSUSE systems you need to enable proxy and proxy_fcgi modules:
```
sudo a2enmod proxy
sudo a2enmod proxy_fcgi
```
For Fedora systems (or others like Archlinux) enable proxy and proxy_fcgi modules by adding (or uncommenting) LoadModule directives in the Apache configuration file - the default location of this file on Linux depends on the distribution. For Fedora (such as RedHat), Archlinux:
```
sudo vi /etc/httpd/conf/httpd.conf
```
For OpenSUSE:
```
sudo vi /etc/apache2/httpd.conf
```
Add this to the end of the file:
```
LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_fcgi_module modules/mod_proxy_fcgi.so
```

- Step 2:
Edit the Apache configuration file:

For Debian (such as Ubuntu):
```
sudo vi /etc/apache2/apache2.conf
```
for Fedora (such as RedHat), Archlinux:
```
sudo vi /etc/httpd/conf/httpd.conf
```
and for OpenSUSE:
```
sudo vi /etc/apache2/httpd.conf
```

Add this to the end of file ("/form" is the application path (see request_URL) and "form" is your application name):

ProxyPass "/form" unix:///var/lib/vv/form/sock/sock|fcgi://localhost/form

- Step 3:
Finally, restart Apache. On Debian systems (like Ubuntu) or OpenSUSE:

sudo systemctl restart apache2

On Fedora systems (like RedHat) and Arch Linux:

sudo systemctl restart httpd

Note: you must not have any other URL resource that starts with "/form" (such as for example "/form.html" or "/form_something" etc.) as the web server will attempt to pass them as a reverse proxy request, and they will likely not work. If you need to, you can change the application path to be different from "/form", see request_URL.

Access application server from the browser

Use the following URL(s) to access your application server from a client like browser (see request_URL). Use actual IP or web address instead of 127.0.0.1 if different.

#Display form 
http://127.0.0.1/form/form_display

#Show data entered 
http://127.0.0.1/form/display_data

Note: if your server is on the Internet and it has a firewall, you may need to allow HTTP traffic - see ufw, firewall-cmd etc.

Files

You are now done with the example! What follows are the source files in this project so you can examine how it works:

Setup database objects (setup.sql)

Create table to hold the first and last name of the guest:

create table if not exists names (firstName varchar(30), lastName varchar(40));

Web form (form_display.vely)

This is a simple HTML web form where first and last name is collected and sent to the server via POST mechanism. Note the path segment after the application path (set with p-path), which is "/form_post", meaning this request will be handled in source file "form_post.vely":

// SPDX-License-Identifier: EPL-2.0
// Copyright 2018 DaSoftver LLC.

#include "vely.h" // must always be here


// 
// Display a web form
//
void form_display ()
{

     out-header default

    @<h2>Enter your name</h2>

    @<form action="<<p-path>>/form_post" method="POST">

    @    <label for="first_name">First name:</label><br>
    @    <input type="text" name="first_name" value=""><br>

    @    <label for="last_name">Last name:</label><br>
    @    <input type="text" name="last_name" value=""><br><br>

    @    <input type="submit" value="Submit">
    @ </form>
}

Submitting web form (form_post.vely)

input-param is used to obtain input parameters sent here from the web form created in "form_display.vely". The data is inserted into the database and the status message output back to web client (i.e. browser):

// SPDX-License-Identifier: EPL-2.0
// Copyright 2018 DaSoftver LLC.

#include "vely.h" // must always be here


// 
// Post input from a web form
//
void form_post ()
{

    out-header default

    input-param first_name
    input-param last_name
    run-query @db_form="insert into names(firstName, lastName) values ('%s','%s')" : first_name, last_name error define err
    end-query

    if (strcmp(err, "0")) {
        @Could not add name, error [<<p-out err>>]
        exit-request
    }

    @Name added to the database<hr/>
}

Display database data in table format in browser (display_data.vely)

This shows typical web output from querying a database. SELECT statement in run-query produces a result set, which is displayed in a tabular format in the browser:

// SPDX-License-Identifier: EPL-2.0
// Copyright 2018 DaSoftver LLC.

#include "vely.h"


// 
// Display table data
//
void display_data ()
{

    out-header default

    @<h2>List of names</h2>

    @<table>
        run-query @db_form="select firstName, lastName from names order by lastName,firstName" output firstName,lastName
    @        <tr>
    @            <td>
                    query-result lastName
    @            </td>
    @            <td>
                    query-result firstName
    @            </td>
    @        </tr>
        end-query
    @</table>

}