Getting Started

Getting Started With SnakeCharmer

Contents

• Getting Started With SnakeCharmer
  • Contents
  • Introduction
  • Packages
  • Setup
  • Running the Scripts
  • Admire Your Handiwork
  • Result
  • Errors

Introduction

This guide is intended as a first step introduction to setting up SnakeCharmer in a development environment.

The following guide should take less than 30 minutes to complete.

Packages

Before we begin, you must have two packages, python 3, and openssl. Using apt we can get them using the following commands:

sudo apt-get install openssl
sudo apt-get install python3-dev

Setup

To start using SnakeCharmer you first need to retrieve a copy of SnakeCharmer. The recommended location for SnakeCharmer is in /usr/local/SnakeCharmer. If you prefer having it located somewhere else, look into [Changing the Location of SnakeCharmer]

First, navigate to /usr/local:

cd /usr/local

Then, retrieve the code using:

sudo git clone git://git.code.sf.net/p/snakecharmer/code SnakeCharmer

Then, move into SnakeCharmer/6.0:

cd SnakeCharmer/6.0

The next step is to generate a certificate for use with HTTPS.

sudo openssl req -new -x509 -keyout server.pem -out server.pem -days 365 -nodes

Next you will need to create a new user to own the database. The default name for this user is pstorage. To create a new user, enter the following in a terminal:

sudo useradd pstorage

And, the owner of storserv_data must be set to this user:

sudo chown -hR pstorage storserv_data

Before moving on, your machine should be set up with a static ip. Go to [Setting Up a Static IP] for instructions. This tutorial will use "0.0.0.0" as an example ip address.

In SnakeCharmer_config.py we must set the server address. This must be set to the static ip address set in a previous step.

:::python
HTTP_WEB_ADDRESS = "0.0.0.0";
HTTPS_WEB_ADDRESS = HTTP_WEB_ADDRESS;

For another example, if your static ip is "192.168.0.135", replace "0.0.0.0" with "192.168.0.135" (including quotes).

(This requirement is a "feature" of the way that http.server.HTTPServer is implemented. The value of this variable may not actually be used in the current implementation. So it may not matter what you set it to.)

We also need to decide on the port at which the server listens. The standard ports for http and https are 80 and 443, respectively, but it may be desirable for testing purposes (or in the case where another web server is already using ports 80, 443) to use other ports (e.g. 8000, 8001). The ports used are set in SnakeCharmer_config.py:

:::python
HTTP_PORT  = 80;
HTTPS_PORT = 443;

In etc_init.d_SnakeCharmer the SNAKECHARMER_USER must be set as a user which can execute the SnakeCharmer script. For security reasons it may be desirable for this user not have access to the storserv_data directory. As an example, I have used the user "stephen".

:::bash
SNAKECHARMER_USER=stephen

However, if SnakeCharmer is to run on the unix privileged ports 80/443, then SnakeCharmer must the run as root.

:::bash
SNAKECHARMER_USER=root

Running the Scripts

For a proper server setup, the web server, [SnakeCharmer], and storage system, [storserv], should begin running when the server is powered on. To do this, the following commands must be executed starting from /usr/local/SnakeCharmer/6.0:

sudo cp etc_init.d_* /etc/init.d/
cd /etc/init.d/
sudo mv etc_init.d_storserv storserv
sudo mv etc_init.d_SnakeCharmer SnakeCharmer
sudo update-rc.d storserv defaults
sudo update-rc.d SnakeCharmer defaults
cd /usr/local/SnakeCharmer/6.0

Now the two scripts must be started. Note that they only need to be manually started this one time because they server hasn't rebooted since the scripts were added. Enter the following commands:

sudo /etc/init.d/storserv start
sudo /etc/init.d/SnakeCharmer start

Now we can begin to use [stosh]. You should read that article if you want to have a greater understanding of how to use stosh. Type the following in a terminal to begin using stosh:

python3 stosh.py

Next, we will create a test page, to verify that SnakeCharmer is working correctly. You should enter the following text into stosh (Note: toor is entered as the password to switch to the root user).

su root
toor
cd Server
cd WebSites
make Object HelloWorld
cd HelloWorld
make Object index
cd index
make Method html

Note: the command in the following picture is python3.1, but executing with python3 should yield the same results

Now, we must modify the method we just created to produce a web page. In stosh type:

edit html

This will prompt you for the editor you would like to use. Examples include vim, nano, and gedit. Inside your editor type in the following and save:

:::python
def html( self, req ):
  req.content_type = "text/html";
  req.content = """
<html>
  <head>
    <title>Example Page</title>
  </head>
  <body>
    <h1>Hello World!</h1>
  </body>
</html>""";

Next, you need to assign the HelloWorld page to a given web URL. You can do this as follows:

 cd ..
 cd ..
 ln HelloWorld _0_0_0_0
 ln HelloWorld www_mysite_org

The two "ln" commands above show how to assign the HelloWorld page to a static IP address and a FQDN, respectively. In this case, the HelloWorld page would be accessible as http://0.0.0.0/ or as http://www.mysite.org.

If it is not a fresh install the root password may have changed, and some of these objects may have already been created. Use ls in stosh to check if attributes have already been created. Go to [stosh] for more details.

Admire Your Handiwork

At this point you are able to open your web browser using a computer on your local network, and navigate to the web page you just created. Set the URL of your browser to https://0.0.0.0:8001 (with "0.0.0.0" replaced by your static ip address).

You should get a warning which states that the website's security certificate is not trusted, but most browsers will let you proceed anyways. This is because the certificate we generated at the beginning is not signed by a trusted party, or is for a different domain.

Result

After following these steps you should get the following result:

Hello World!

Before proceeding on your own you should read the [Getting Started Explanation] to get a greater understanding of how SnakeCharmer works.

Errors

If you are having problems that are not covered below, please contact the developers using the discussion forum.

There are currently no frequently occurring errors to address.