Test Server Installation and Configuration

From NSB App Studio
Jump to navigation Jump to search

Front Matter

The following instructions will walk you through installing and configuring an AppStudio Test Server. They assume you have a basic understanding of how to use computers, but no prior knowledge otherwise. You will be installing Ubuntu Server, which is a Linux distribution. You should have physical access to the server you are installing on, though it is possible to install to a virtual server that you can remote into. These instructions will not work for a shared hosting environment, that is, an environment where you do not have root access (otherwise known as administrative or super user access) to the server.

Determining the CPU Type

The following instructions assume you are installing on a 64-bit machine. You can determine if your machine is 64-bit capable by looking up your CPU by model number. You can generally find the CPU type in the BIOS Setup, which is normally accessed on boot by pressing a function key or the delete key. Intel CPU model numbers tend to look like a letter and 4 numbers, for instance: T7600. Once you have the CPU model, you can verify it has a 64-bit instruction set by looking up the CPU on Intel's site. For instance:

Most modern CPUs are 64-bit.

These instructions have not been tested on a 32-bit machine. However, they should work with minimum changes. If you are planning to install on a 32-bit machine, you should download the x86 image: http://releases.ubuntu.com/precise/ubuntu-12.04.4-server-i386.iso

Create Bootable Media

  1. Download Ubuntu Server 12.04.4 LTS 64-bit: http://releases.ubuntu.com/precise/ubuntu-12.04.4-server-amd64.iso
  2. Determine if you will be writing the ISO file to a CD or a USB drive.
    1. CD: simply write the ISO image to a writable CD. Detailed instructions are available here for many operating systems: https://help.ubuntu.com/community/BurningIsoHowto
    2. USB drive: writing to a USB drive can be a bit tricky. It's suggested that you use Linux Live USB Creator on Windows (http://www.linuxliveusb.com/en/home). Detailed instructions (and instructions for other OSes) can be found here: https://help.ubuntu.com/community/Installation/FromUSBStick

Install Ubuntu

This section assumes you have physical access to the machine. Generally, a virtual server host will automate this step.

More detailed install instructions can be found here: https://help.ubuntu.com/lts/serverguide/installing-from-cd.html

  1. Boot your Ubuntu media. This may require you to either hold down a key during boot or change the boot device order in the BIOS settings. Instructions vary depending on your model of server.
  2. You will be prompted to choose a language. Choose the appropriate language.
    Screenshot01.png
  3. Choose the option "Install Ubuntu Server"
    Screenshot02.png
  4. Select your language once again.
    Screenshot03.png
  5. Select your location.
    Screenshot04.png
  6. Select your keyboard layout by allowing the installer to auto-detect it.
    Screenshot05.png
  7. At this point, your server will try to configure its network connection. Generally, the network will be configured automatically. If your network configuration fails, you will have to configure it manually. Speak to your network administrator or hosting company for the proper configuration values.
  8. Enter a hostname for this machine. If this machine already has a name on your network, use that. This does not include the domain name. For example, "server01" and not "server01.example.com".
    Screenshot06.png
  9. Enter in the real name of the initial user.
    Screenshot07.png
  10. Choose a name for the initial user. This user will have administrative privileges but will not be a super-user.
    Screenshot08.png
  11. Choose a password for the initial user and verify it.
    Screenshot09.png
  12. Choose to not encrypt your home folder.
    Screenshot10.png
  13. Choose your timezone.
    Screenshot11.png
  14. Choose to use Guided Partitioning, using the entire disk, with LVM.
    Screenshot12.png
  15. Select the proper disk.
    Screenshot13.png
  16. Write the changes to disk.
    Screenshot14.png
  17. Choose to use the entire disk again.
    Screenshot15.png
  18. Verify you will write changes to the disk again. The base system should now install.
    Screenshot16.png
  19. Setup an HTTP proxy, if you need one.
    Screenshot17.png
  20. Choose to install automatic updates.
    Screenshot18.png
  21. Choose to install the OpenSSH server.
    Screenshot19.png
  22. Install GRUB to the master boot record.
    Screenshot20.png
  23. Reboot.
    Screenshot21.png

Domain Names

The remainder of these instructions assume you have a host and domain name configured externally for the server. A domain name server maps the server's IP address to a name, for instance 10.1.1.2 to server01 (or server01.example.com if the domain name is "fully qualified"). If you don't have an external domain name server, some of the following instructions will not work. You can either speak with your network administrator to get a DNS (domain name server) entry created, or you can modify the "hosts" file of the computer from which you will be configuring the server. The following link describes how to modify your "hosts" file on Windows, Mac OS, and Linux: http://www.rackspace.com/knowledge_center/article/how-do-i-modify-my-hosts-file

Add the following entry into the "hosts" file:

10.1.1.2 server01

Replace 10.1.1.2 with the IP address of your server and "server01" with the host name of your server.

Remote Access

At this point, you should be able to login to your server using SSH. SSH stands for secure shell. It allows you to bring up a command prompt from another machine. If you are on Mac OS or Linux, you can open a Terminal and type:

ssh user@server01

Replace "user" with the user you created while installing and "server01" with your server's hostname. When you first connect you will be prompted to verify you want to connect to the host.

If you are on Windows, it's suggested you use PuTTY: http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html. Documentation is available here: http://the.earth.li/~sgtatham/putty/0.63/htmldoc/Chapter2.html

If you can't login, there's a chance there's a problem with your network configuration. SSH uses port 22. Verify it's not being blocked by a firewall by speaking with your network administrator.

Upon logging in, you should see the following:

Screenshot22.png

Configuring

Once your computer has rebooted, login using the username and password you created during the install process. The remainder of this tutorial assumes a basic familiarity with Bash, navigating folder structures from the command prompt in Unix based environments (Linux, Mac OS, etc...), editing text files, and scripting. If you aren't comfortable with these topics, here are several tutorials that may help:

Using sudo

The "sudo" command allows you to run commands as a super user (Super User DO) without being a super user yourself. Because this guide is focused on administrative configuration of a server, many of the commands are proceeded by "sudo".

When running a command prefixed by sudo, you will be prompted to enter your password. For the next 15 minutes, you will not have to enter your password. However, if you walk away from the computer and the screen blanks, or more than 15 minutes elapses, you will again have to enter your password.

Update Packages

At the command prompt, type the following:

sudo aptitude update
sudo aptitude full-upgrade

Screenshot23.png

Follow the prompt, and after the upgrade is complete, install apache, vsftpd, and incron:

sudo aptitude install apache2 vsftpd incron

Finally, reboot:

sudo reboot

Configure Apache

From the command prompt, switch to the following folder:

cd /etc/apache2/sites-available

Create a new site by creating a new text file:

sudo nano asserver

Paste the following content into the file, changing the ServerAdmin, ServerName, and ServerAlias to values that make sense for your server:

<VirtualHost *:80>
        ServerAdmin admin@example.com
        ServerName www.example.com
        ServerAlias example.com

        DocumentRoot /srv/ftp/home
        <Directory /srv/ftp/home/>
                Options FollowSymLinks
                AllowOverride None
                Order allow,deny
                allow from all
        </Directory>

        ErrorLog ${APACHE_LOG_DIR}/error.log

        # Possible values include: debug, info, notice, warn, error, crit,
        # alert, emerg.
        LogLevel warn

        CustomLog ${APACHE_LOG_DIR}/access.log combined

</VirtualHost>

Screenshot24.png

Save the file using Ctrl-O, verify the file name, and then exit with Ctrl-X. Next, enable the site by making a symbolic link:

sudo ln -s ../sites-available/asserver ../sites-enabled/asserver

Next, make the document root specified above:

sudo mkdir -p /srv/ftp/home

Finally, restart apache:

sudo /etc/init.d/apache2 restart

Verify that you receive a forbidden error when navigating to your server in a web browser. If you place an html file in your web root, you should be able to navigate to that as a further test.

Configuring VSFTPD

Using nano, make the following modifications to /etc/vsftpd.conf:

sudo nano /etc/vsftpd.conf
  • Uncomment write_enable=YES
  • Change anonymous_enable=YES to anonymous_enable=NO
  • Uncomment local_enable=YES
  • Uncomment local_umask=022
  • Add the following lines:
delete_failed_uploads=YES
pasv_min_port=50000
pasv_max_port=50100
port_enable=NO
chroot_local_user=YES
passwd_chroot_enable=YES

Save the file using Ctrl-O, verify the file name, and then exit with Ctrl-X.

Add an FTP user to the system, and set its home folder to "/srv/ftp/./home":

sudo adduser ftpuser
sudo usermod -m -d /srv/ftp/./home ftpuser

Screenshot25.png

Give ftpuser rights to /srv/ftp/home:

sudo chown ftpuser:ftpuser /srv/ftp/home

Restart vsftpd:

sudo /etc/init.d/vsftpd restart

Verify you can upload files by connecting via FTP as the user you just completed. They should appear in the web root. If you need an FTP client, WinSCP (http://winscp.net/eng/index.php) is a popular choice for Windows and Cyberduck (http://cyberduck.io/) is a popular choice for Mac OS.

Creating the proper folder structure

Start by creating the folders to support template uploads and setting their permissions:

sudo mkdir -p /srv/ftp/NSB_UPLOAD_COMPLETED
sudo mkdir -p /srv/ftp/templates
sudo touch /srv/ftp/NSB_UPLOAD_COMPLETED/.locked
sudo chown ftpuser:ftpuser /srv/ftp/NSB_UPLOAD_COMPLETED

Make template folders for all the versions of AppStudio you wish to support - for instance:

sudo mkdir -p /srv/ftp/templates/3.2.x

Uploading the "nsb" Folder

First, you will need to locate the "nsb" folder, and upload it to your home folder. The directions vary by operating system.

Windows

  • Navigate using Windows Explorer to "C:\Program Files (x86)\NSB AppStudio\". On older systems, the folder may be "Program Files" without the "(x86)".
  • Copy the "nsb" folder to your desktop.
  • Download and install an SFTP client, such as WinSCP: http://winscp.net/eng/index.php
  • Connect to your server using the following instructions as a guide: http://winscp.net/eng/docs/guide_connect
  • WinSCP should default its remote location to your home folder on the server. Upload the "nsb" folder on your desktop to your home folder using the following instructions as a guide: http://winscp.net/eng/docs/guide_upload

Mac OS

  • Navigate to the "Applications" folder on "Macintosh HD".
  • Find the AppStudio icon and right click on it.
  • Choose "Show Package Contents"
  • In the Finder window that appears, navigate to "Contents/Resources".
  • Copy the "nsb" folder to your desktop.
  • Open the Terminal application in Mac OS, and type the following:
cd ~/Desktop
scp -r nsb user@server01:.

Be sure to replace "user" and "server01" with your username and server's hostname.

Copying "nsb" to the Template Folder

Finally, copy the "nsb" folder to the template folder you created. While logged into your server, type the following:

sudo cp -R ~/nsb /srv/ftp/templates/3.2.x/

Configuring incron

First, create the link script in the template folder with the following command:

sudo nano /srv/ftp/templates/link.sh

Copy the following into link.sh using nano:

#!/bin/bash

if grep --quiet '<meta name="generator" content="NSB/AppStudio 3.*" />' /srv/ftp/home/$1/index.html; then
    ln -s /srv/ftp/templates/3.2.x/* /srv/ftp/home/$1
fi
# add elif lines for more templates

rm /srv/ftp/NSB_UPLOAD_COMPLETED/$1

Save the file using Ctrl-O, verify the file name, and then exit with Ctrl-X.

Mark it executable:

sudo chmod a+x /srv/ftp/templates/link.sh

Next you need to configure incron for ftpuser. First allow ftpuser to use incron by creating the following file:

sudo nano /etc/incron.allow

Add the following content to the file and save with Ctrl-O, verify the file name, and then exit with Ctrl-X:

ftpuser

Edit ftpuser's incrontab:

sudo incrontab -u ftpuser -e

This brings up an editor. Paste the following content into the editor:

/srv/ftp/NSB_UPLOAD_COMPLETED IN_CLOSE_WRITE /bin/bash /srv/ftp/templates/link.sh $# > /dev/null 2>&1

Save the content with Ctrl-O. Incron should now be configured. You can verify this by creating a folder in /srv/ftp/home and then creating a file in /srv/ftp/NSB_UPLOAD_COMPLETED that shares the folder's name. The file you created should be removed and the folder should contain a link to your template.

Uploading & Verification

If everything has been configured correctly, you should be able to connect via FTP upload files using AppStudio's protocol, described below.

AppStudio Upload Protocol

AppStudio uploads projects to a test server with the following steps:

  1. Choose a unique prefix for the folder based on the user's registration.
  2. Connect via FTP and upload the prefixed project folder into the ftp home folder.
  3. Change folders to ../NSB_UPLOAD_COMPLETED and drop a file in that folder that matches the name of the folder you just uploaded.

You can follow these steps manually to test the system.

Verification

If the system is working properly, a symbolic link to the template should have appeared in your project's folder after uploadng. Also, the file uploaded to NSB_UPLOAD_COMPLETE should have been removed.

It's important to note, that if the uploaded project does not contain "index.html" or the included "index.html" file does not contain a proper generator string (e.g. <meta name="generator" content="NSB/AppStudio 3...) the template files will not be linked. Also, if the template files already exist in the upload, they will not be replaced by a link.

Verification with AppStudio

You cannot verify the complete functionality of the server with AppStudio. You can, however, test he FTP and HTTP components of the server by configuring AppStudio to upload to your server directly:

  • Go into AppStudio's Preferences:
    • Windows: This will be in the Tools menu.
    • Mac OS: This will be in the AppStudio menu.
  • Change the Deployment Location to "Deploy to server listed below". You will only be able to perform this step if you have a registered copy.
  • Set the server to the hostname or IP address of the server you've just configured
  • Set the username to the name of your ftp user.
  • Set the password to the password of your ftp user.
  • Click OK.

Screenshot 2014-02-03 20.17.14.png

Now, when you deploy your application, you should be able to access it at: http://[servername]/[projectname]/