Instance Access for Development

From TechWiki

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 conStruct). 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:

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.

The Directory Structure

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

https://help.ubuntu.com/community/LinuxFilesystemTreeOverview

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
structWSF: /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						conStruct				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.