CIS-1152 Lab #9: Setting Up Lemuria

In this lab you will configure your account on the CIS Linux system Lemuria for doing PHP development there.

Part 1: Setting Up Your Account

Do the following steps to enable your website on Lemuria.

You should have received Lemuria credentials in email (unless you already have an account there). If you did not receive those credentials, don't know if you have an account, or forgot your password, contact the instructor to get your account created or your password changed.
Set up an SSH client on your system for accessing Lemuria's shell. Many such clients exist. Any of them will work fine. PuTTY is a free SSH client program for Windows. It is relatively simple, yet provides a rich collection of features. I have a document that describes how to set up and use PuTTY to access Lemuria (you only need to do the steps in Part 1 of that document). If you are a Mac user, you might find these notes about SSH on the Mac useful.
Once you are logged into Lemuria, you should change your password so it is not the same as the initial password set on your account. Use the following command:
```
      $ passwd
    
```
In this command, and all others in this lab, the $ symbol is the system prompt. Do not type that part. Note that when you enter your passwords you will not see any text, not even '*' characters. Type carefully.
To display web pages on Lemuria, you should create a folder named public_html to hold your pages. You must use this name. You will also need to grant permission for the web server to access the files in that folder. The issue is giving the web server enough access to your home directory (where all your files are located) without giving other users any access. Use the following commands (replace username with your username):
```
      $ mkdir public_html
      $ setfacl -m user:www-data:--x /home/username
    
```
The setfacl command modifies (-m) the access control list (ACL) on your home directory to add the execute (x) permission for the www-data user. That is the user account under which the web server runs.
Check if things are set up correctly be creating a trivial web page in public_html. You can use the nano text editor. For example:
```
      $ nano public_html/index.html
    
```
After you have saved the file, try to load it into a web browser using this URL:
```
      http://lemuria.cis.vtc.edu/~username
    
```
Replace username with your actual username. Lemuria's web server is accessible from outside the VTSU firewall. Your pages can be seen from anywhere in the world.

Part 2: Setting Up PhpStorm

It will be convenient to using PhpStorm to remotely access and work on your Lemuria web pages. We will not be using XAMPP. Do the following:

Begin by being sure you have the latest version of PhpStorm installed. If an "Update" button appears in the JetBrains Toolbox app, click on the button and let the update complete (be sure PhpStorm is closed before trying to update it).
In the JetBrains Toolbox app, install the "Gateway" program. You don't need to do anything with this directly, but it has to be installed. Note that it is a beta program. If, in the future, it offers you an update, accept the update.
Open PhpStorm and select "File" -> "Close Project" to close your currently open project. You should be looking at a small start-up window. On the left side of that window, click on "Remote Development" then click on "New Connection" under "SSH Connection." Fill in your username (on Lemuria) and the host "lemuria.cis.vtc.edu." Be sure to change the port to 2221. Click on "Check Connection and Continue."
In the dialog box that follows you will be prompted to install PhpStorm 2023.1 RC. This will install PhpStorm in your account on Lemuria. Go ahead and let that happen. Specify as the "Project Directory" where your website is located on Lemuria. You can click on the three dots and then navigate to /home/username/public_html. Finally click on "Start IDE and Connect."

It takes a few moments to install and launch PhpStorm on the remote end. Eventually you should see your website on Lemuria in a normal PhpStorm window. Make a change to your site and verify that the change is visible via Lemuria's web server.
When you are done, close the JetBrains Client. You will be asked if you want to keep "the backend IDE" running. If you say "yes", reconnecting to your project later will be a little quicker, but it does consume more resources on Lemuria. I suggest saying "no" if are not planning to return to your development right away. Also, given that this is a beta system, you may have more stability if you restart the IDE fresh each time.

Part 3: Alternative PhpStorm Configuration

You only need to do this part if you have problems with the PhpStorm configuration described above!

The remote development feature of PhpStorm used above is currently in beta and thus subject to some degree of instability. Some students have had odd issues preventing them from using PhpStorm as described above (but not everyone, so if it is working for you, skip this part).

Configure an SSH Tunnel

The SSH protocol allows you to "tunnel" other connections over an SSH connection. This feature is also called "port forwarding". It can be used to make remote services appear as if they are running on your own computer.

Once you configure an SSH tunnel that connects to the PostgreSQL server on Lemuria, you will be able to store your pages and run PhpStorm entirely on your own machine, as you have been doing, without needing the remote development feature at all. When you connect to the database server, you will connect to the local end of the SSH tunnel which will then forward the traffic to the remote system (Lemuria) where a connection will be made to the PostgreSQL server behind the firewall. You can use PuTTY to set up the tunnel.

In your PHP, you will connect to the database server at "localhost" at the PostgreSQL default port of 5432, log in as "jjones" with the standard password. You also need to log into Lemuria via PuTTY before trying to use the tunnel, and you should stay logged into Lemuria for the entire time that you need the tunnel. Only log out of Lemuria after you have shutdown PhpStorm and stopped working on your project for the day.

Enable the PostgreSQL PHP Drivers

The PHP processor that comes with XAMPP is pre-configured to use the MariaDB database management system that is part of XAMPP. To use PostgreSQL it is necessary to configure XAMPP's PHP processor to also load the PostgreSQL extensions. Fortunately, those extensions are shipped with XAMPP; it is only a matter of enabling them. Follow this procedure:

If PhpStorm is running, close it. You must be sure the PHP processor PhpStorm previously loaded (if any) is not running.
Edit C:\xampp\php\php.ini in a text editor. Search for the lines that look like:
```
      ;extension=pdo_pgsql
      ;extension=pgsql
    
```
They are around line 937 in the file, almost back-to-back.
Remove the semicolon at the start of those lines to enable the extensions. Save the file.
You can now restart PhpStorm. PhpStorm's internal web server should now recognize the PDO interface and be able to connect to PostgreSQL.

Enabling the PostgreSQL extensions in XAMPP's PHP processor also allows XAMPP's Apache web server to interact with PostgreSQL. So, if you prefer to use XAMPP's Apache for testing rather than PhpStorm's internal web server, no additional configuration is necessary.

Part 4: Database Access

You will want to configure your project to access the FoodTracker database on Lemuria. Do the following:

Finish Me!

There is nothing specific to submit for this lab. I will check that your website "works" in the sense that there is something there. This lab is worth 10 points.