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

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:

Winscp.png

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.

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.

<root>

data


configs



apache2




sites-available Web sites configuration files



mysql configuration files



php configuration files



phpmyadmin configuration files



solr configuration files


ontologies


files mostly external ontologies



structure internal; do NOT alter

etc


[multiples] configuration files

usr


local



virtuoso-opensource




[multiple directories/files] Virtuoso application


share MAIN DESTINATION



drupal Drupal destination




data




doc




includes




modules





[multiple standard modules]




ontologies




profiles




scripts




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





[multiple sites]





mysite.com






files







icons location of site app icons







images location of site app images








temp standard image placeholder directory






logs Apache requires, with set internal files
XXXX



modules

XXXX



OSF-Drupal generally, will not need to modify


XXXX



css



XXXX


framework




XXXX

imgs





XXXX
js






XXXX modules







XXXX [multiple]








XXXX [structIndividual]









XXXX css some styling options here










imgs








templates









owl_thing.html generic, fallback Smarty template









[more templates] potential for many multiples here






themes







garland default theme with initial install







our_theme








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



mediawiki




[more] application files



mysql




[more] application files



php5




[more] application files



phpmyadmin




[more] application files



solr




[more] application files



structwsf




[multiple directories/files] base application code



websites




[specific sites] static sites and Web pages

var

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.