Archive 1.x:Instance Access for Development

This document describes the basic methods for accessing and doing development on a remote instance based on the open semantic framework (OSF) stack. The material also describes the basic file structures and layouts of these instances. Some of the useful tools for doing development on a remote instance are provided in the Desktop Development Environment.

Please also note that being familiar with the directory structure of your remote instance is very important.

Interacting via Drupal
For content management, content additions, site management and module (functionality) purposes, you will often need to interact directly with the Drupal directory structure or files (as the host of OSF-Drupal). This is likely the predominant development mode of interacting with your site.

During the development phase it is advisable to keep the site offline and restrict access to authorized (password-protected) users only. The site is taken on- and off-line via the Admin within Drupal. To do so, access  ->   ->. You may also set the offline welcoming notice at this location.

Then, when standard users encounter your site, such as at http://yoursite.com, they will only see the offline welcoming notice.

Any of your authorized users with admin rights may bypass this screen and access the system by going to http://yoursite.com/user and entering their login specifics. Once logged in, these users may see and modify the site as it is intended to be for ultimate public release. Public release then occurs by switching the site to online.

Direct Drupal Interaction
For adding new content, editing it, configuring modules and themes and many other options, you can work directly with those settings from within the Drupal application itself. Each major area of Drupal (themes, users, modules, blocks, views, etc.) has its own conventions and best practices. See further the Drupal category on this site or the many sites available on the Web for these purposes.

Code Interaction with Drupal
However, for the development purposes of:
 * Theme or module installations and upgrades
 * Drupal upgrades
 * Direct stylesheet access, or
 * Direct code (PHP) access

you will need to directly access the directory structure and files of your remote instance. The remaining portions of this document deals with these questions.

Accessing the Remote Instance
There are many tools and many methods to access a remote instance. This example is based on WinSCP and PuTTY using SSH and public keys.

WinSCP
WinSCP is an open source SFTP client and FTP client for Windows. Its main function is the secure file transfer between a local and a remote computer. Beyond this, WinSCP offers basic file manager functionality. It uses Secure Shell (SSH) and supports Secure FTP.

Prior to configuring and logging in with WinSCP, make sure you have a proper public key and it is stored in a known location (directory) that you can access. If so, then start up the WinSCP application, which will bring you to the initial configuration screen:



Enter the IP address (such as 12.34.567.890) under the Host name and your login name (associated with your public key) as well. Make sure you have the Advanced options checked. Then, enter the directory location where your passkey is located.

It is then a good idea to save this configuration, and give it a name such as MyInstance. Then, next time you login, all of this login information will now be saved for you:



Upon Login, you will see confirmation of a handshake with the remote server, and then you will be prompted for the passphrase (password) for the same user account associated with your key. Enter it at the bottom entry:



The first time you successfully login to the remote instance you will be prompted about placing your key in cache. Agree to do so; you will not see this screen again.

Upon a successful login, you will be presented with the WinSCP management screen. Here is an example of the "classic" (two pane) configuration:



The first time you access your remote instance you will be placed at the root of your local directory (left-hand panel) and remote directory (right-hand panel). You can navigate to any directory location of your choosing locally or remotely, and then Save your session using the same session name. This enables you to start up the WinSCP application next time in your desired directory locations.

The view above has saved the session for the Drupal directory locations (both locally and remote). To get to this location on the remote instance, refer to the Directory Structure information shown below.

Using WinSCP
You navigate the directory structures by double-clicking on the folder icons. Clicking on a parent directory also causes you to move up one level (to the parent). You can also create, delete and rename directories.

The basic use of WinSCP is to transfer files seamlessly between your local directory and the remote instance. You do this by dragging-and-dropping file(s) from one pane to the other. You may also use the standard copy and paste commands.

You can thus do development locally and then upload the updated files to the remote instance.

Some Best Practices

 * For the OSF stack the remote instance uses the Linux operating system. All file names in Linux are case sensitive, so exercise special care in consistency of naming. Generally, it is safest to use all lowercase in file names.
 * It is generally advisable to first copy the operating files from the remote instance to your local directory before making any changes. This practice is especially advisable if multiple individuals may be making changes. By always starting with the remote instance, you are assured of working with the current operational version.

PuTTY
PuTTY is a free implementation of Telnet and SSH for Windows and Unix platforms, along with an xterm terminal emulator. Unless you are an admin or are doing command line modifications of a remote server, the WinSCP tool should be sufficient for access and management of a remote instance.

Working Directly with the Instance
You will need a client such as WinSCP (see above) to access the remote instance directly.

Theming Code
Theming customization in Drupal is largely done (apart from built-in options) via cascading style sheets (CSS). The specific file to be modified for a given theme for your remote instance is found under:  ->    ->   ->   ->.

There are many useful theming and CSS sites on the Web. Two very useful references are:
 * Quick Reference Guide to Cascading Style Sheets
 * CSS2 Specification.

Layout Code
Layout customization in Drupal may also occur via a series of template PHP pages for the given theme. The various files to be modified for such purposes may be found in your remote instance under:  ->    ->   ->   ->.

To make modifications here requires a modicum of PHP knowledge, as well as the templating conventions used in Drupal.

For basic PHP guidance, see the simple tutorial for the language.

For basic Drupal theming understanding, see an overview of theme files.

Data and Other Code
Storage and access to OSF data may be placed anywhere on the remote instance. Generally, it is best to keep it localized near the Drupal directories or similar under the  directories.

Specific ways to access or maintain data sources for OSF are beyond the scope of this document.

NOTE: The idea is good, but would require complete re-write. Not necessary for release.