Archive 1.x:Instance Access for Development

From OSF Wiki
Jump to: navigation, search
Important yellow.pngThis page needs to be updated to OSF v. 3.0; terminology and perhaps images are out of date !!!

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 Administer -> Site configuration -> Site maintenance. You may also set the offline welcoming notice at this location.

Then, when standard users encounter your site, such as at, 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 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 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:

Winscp config.png

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:

Winscp login.png

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:

Winscp passphrase.png

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 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.

The Directory Structure

For general questions regarding the "standard" directory structure of a Linux installation, see for example:

Different flavors of Linux have different directory structures. However, since the OSF installation guide is premised on Ubuntu, we use it as the general reference.

Locations from Root

The two key locations you need to know from the initial <root> location are:

  • Drupal: /usr/share/drupal
  • OSF Web Service: /usr/share/structwsf/

Relevant Directory Structure

There is much contained on a remote instance. The listing below, however, highlights some of the particular directory locations -- with comments -- of importance to the open semantic framework.





sites-available Web sites configuration files

mysql configuration files

php configuration files

phpmyadmin configuration files

solr configuration files


files mostly external ontologies

structure internal; do NOT alter


[multiples] configuration files




[multiple directories/files] Virtuoso application


drupal Drupal destination





[multiple standard modules]




site everything is accessed below here; ignore the other Drupal sections

[multiple sites]


icons location of site app icons

images location of site app images

temp standard image placeholder directory

logs Apache requires, with set internal files



OSF-Drupal generally, will not need to modify








XXXX modules

XXXX [multiple]

XXXX [structIndividual]

XXXX css some styling options here



owl_thing.html generic, fallback Smarty template

[more templates] potential for many multiples here


garland default theme with initial install


images images specific to the theme rendering

style.css MOST IMPORTANT: style sheet for theme

block.tpl.php base block template; others possible

node.tpl.php base node template; others possible

page.tpl.php base page template; others possible

page-front.tpl.php may have a different front page look

template.php general theme settings

settings.php major point for specific app configuration settings

themes default fallback; use sites instead


[more] application files


[more] application files


[more] application files


[more] application files


[more] application files


[multiple directories/files] base application code


[specific sites] static sites and Web pages


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: sites -> mysite -> themes -> mytheme -> style.css.

There are many useful theming and CSS sites on the Web. Two very useful references are:

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: sites -> mysite -> themes -> mytheme -> *.tpl.php.

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 usr/share 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.