From Cyclopath

These notes discuss how to set up Cyclopath. They are fairly complete, but they are disorganized in places and may be redundant with other parts of the tech docs.

Please note that this install guide is not maintained by the Cyclopath team.

See also Tech:Open Source/Install Guide, Tech:Installing and Tech:Source_Code.

Contents 1 Cyclopath Installation Notes 1.1 Overview 1.2 Foreword 1.3 Install Linux 1.3.1 Virtual Machine (VM) 1.3.1.1 Which VM? 1.3.1.2 Sun VirtualBox 1.3.1.3 VirtualBox Gotcha! 1.3.2 Install Linux on the VM 1.3.3 Basic Linux Setup 1.3.3.1 Setup Sudoers 1.3.3.2 Customize Gnome 1.3.3.3 Helpful Development Apps 1.4 Install Cyclopath 1.4.1 Cyclopath Environment Setup 1.4.1.1 Bash Setup 1.4.1.2 Install Core Packages 1.4.1.3 Setup for Group Development 1.4.1.4 Configure Services 1.4.2 Browser and Flash Setup 1.4.3 Running Cyclopath 1.5 Development Tips 1.6 Online Resources

[edit] Cyclopath Installation Notes

[edit] Overview

This document describes how to build and install Cyclopath from source on Ubuntu 9.04 using VirtualBox.

[edit] Foreword

These instructions are elaborated from many of the other pages in the Wiki. The other pages are concise; the pages herein are not. This guide is meant to be a step-by-step guide. As such, we're clear to document what OSes, versions, etc., because your results may (always) vary.

[edit] Install Linux

[edit] Virtual Machine (VM)

Unless you have a machine dedicated to Cyclopath development, it's recommended that you install Cyclopath in a fresh Linux distribution using a virtual machine.

This minimize the risk that you'll mess up your computer. If you mess up a virtual machine image, you can quickly restore a snapshot, rather than reinstalling the whole OS. Second, using a VM simplifies finding video and audio drivers, since the VM supplies its own. Lastly, Cyclopath requires certain versions of certain applications (Apache, Postgres, SVN, etc.) and isolating those in a dedicated virtual machine keeps you from having to change your existing environment.

[edit] Which VM?

There are a lot of platform virtual machines to choose from.

For a comprehensive list, see Wikipedia's Comparison of platform virtual machines.

We chose Sun's VirtualBox because it's free (GPL2), it's actively developed, it works (at least for me, on Windows Vista [^landonb] ;), and it works fast.

[edit] Sun VirtualBox

VirtualBox is available for multiple platforms.

Currently, we have documentation for installing VirtualBox on Windows.

• Install VirtualBox on Windows

If you have notes on installing VirtualBox on another host OS, please feel free to add to the following pages.

• Install VirtualBox on Ubuntu
• Install VirtualBox on Fedora
• Install VirtualBox on Mac OS X
• Install VirtualBox on Solaris
• Install VirtualBox on FreeBSD

[edit] VirtualBox Gotcha!

There's a bug in the current version of VirtualBox on Windows Vista, and it may affect other operating systems or hardware configurations.

Warning When I shutdown the guest on Vista while fullscreen or maximized, the next time I start the virtual machine, it hangs while booting the X server (black screen with blinking white underscore). [^landonb]

(To be honest, I don't know what causes the bug, so it could be a host video driver, it could be a VirtualBox video driver, it could be something else, who knows. I searched on the bug but couldn't find anything meaningful.)

I would suggest installing VirtualBox and the Guest Additions, taking a snapshot while not maximized/fullscreen, shutting down the guest, rebooting, going fullscreen, then shutting down again and rebooting and seeing if it works. If so, great; otherwise, restore the snapshot and don't try that again.

(The shortcut for fullscreen is pressing the Host key (usually the Left Alt key) along with F.)

Feel free to add your own experiences here!

[edit] Install Linux on the VM

These instructions are based on Ubuntu 9.04 (Jaunty) 64-bit. Cyclopath is also known to run on Ubuntu 8.04 (Hardy) 32-bit.

FIXME Some of these instructions were gleaned from Fedora x64 on VirtualBox; this needs to be corrected. And does anyone want 32-bit Ubuntu documented? What about 9.10? 8.04?

• Install Ubuntu 9.04 Jaunty on VirtualBox

[edit] Basic Linux Setup

The following steps are suggested. They're not required. But they might make the dev life easier.

[edit] Setup Sudoers

Save time but not repeating yourself. Add yourself to the sudo list so you don't have to type your password all the time.

• Edit Sudoers

[edit] Customize Gnome

Everyone has particular tastes when it comes to customizing their window manager. Heck, some people don't even run Gnome! This step isn't necessary for developing Cyclopath, but take a peak nonetheless.

• Customize Gnome

[edit] Helpful Development Apps

There are some useful development applications that are nice to have, but these also aren't necessary to run Cyclopath.

• Helpful Apps

[edit] Install Cyclopath

[edit] Cyclopath Environment Setup

[edit] Bash Setup

For VirtualBox, you don't need a special Bash configuration. Core developers, on the other hand, do need a special Bash configuration.

In either case, read on for some handy Cyclopath development shortcuts you might find useful.

• Create or download Bash Scripts

[edit] Install Core Packages

Ubuntu and Fedora use package managers, namely aptitude and yum, respectively. These make setting up your machine pretty easy.

Please follow the instructions for the specific guest operating system you are running.

• Install core packages for Ubuntu 9.04
• Install core packages for Fedora 12

[edit] Setup for Group Development

It is especially important for core developers to get setup properly for group development. Independent Open Source users can skip this step.

• Setup for Group Development

[edit] Configure Services

Follow these steps to configure applications for Cyclopath development. You'll also need to download and install a few applications not provided by the package managers.

• Configure PortgreSQL
• Compile GIS Apps
• Configure Apache

[edit] Browser and Flash Setup

Most Cyclopath developers use Firefox for development (though Cyclopath supports a number of additional browsers).

To install Firefox for development, read the following.

• Install Firefox and Flash

Regarding other browsers, not all of the supported browsers can be used to develop Cyclopath. E.g., Google Chrome on Ubuntu x64 does not support the 32-bit Flash Debug Plugin, whereas a custom-built Chromium browser (the same source as Google Chrome) does work with the 32-bit plugin.

• Notes on Other Browsers

[edit] Running Cyclopath

Get up and running in four easy steps! (Well, ignoring the 20 steps you just took! ;)

FIXME Make these pages. For now, please see Getting the Source Code.

1. Checkout the Source
2. Seed the Database
3. Build the Services
4. Run It!

[edit] Development Tips

See debugging hints for tips on debugging Python and Flex, as well as diagnosing problems with Apache, Postgres, etc.

• Debugging Hints

[edit] Online Resources

Adobe has exhaustive documents on developing Flash (a/k/a ActionScript, a/k/a Flex)... if you know where to look.

FIXME I'm not sure these match the versions Cyclopath uses. Also, I usually just Google "flex blah blah" when looking for help.

• Flash CS3 Documentation
• ActionScript 3.0 Reference

Curious how to format documents for the Cyclopath Wiki? Check out the official reference.

• Wiki Markup Reference

FIXME Need links to Python docs, PostGIS, MapServer, etc., etc.