Development Production Line

The Short Story

2.1-beta Edition

Published 7 January 2013


Table of Contents

1. Operating System
1.1. Windows
1.1.1. Resources
1.1.2. Desktop
1.1.3. Explorer
1.1.4. Windows 7 Start Menu
1.1.5. Task Manager replacement
1.1.6. Symbolic links
1.1.7. User Account Control replacement
1.1.8. Windows Update
1.1.9. Antivirus
1.1.10. Command Processor
1.1.11. Services
1.1.12. Data Execution Prevention
1.1.13. Archive Tools
1.1.14. GnuWin32
1.1.15. Text editor
1.1.16. Merging tool
1.1.17. Secure Shell
1.1.18. File Transfer
1.1.19. Graph Visualization Software
1.1.20. Debugging Tools
1.1.21. Viewers
1.1.22. Utilities
2. Browser
2.1. Firefox
2.1.1. Resources
2.1.2. Firefox installation guide
2.1.3. Firefox preferences
2.2. Safari
2.2.1. Resources
2.2.2. Safari installation guide
2.3. Chrome
2.3.1. Resources
2.3.2. Chrome installation guide
3. Programming Languages
3.1. Java 2 Platform
3.1.1. Resources
3.1.2. JDK installation guide
3.2. C#
3.3. C++
3.4. Python
3.4.1. Resources
3.4.2. Python installation guide
3.4.3. Python Enterprise Application Kit
3.4.4. Pygments
3.5. Perl
3.5.1. Resources
3.5.2. Perl installation guide
3.5.3. Perl Package Manager user guide
3.6. Simplified Wrapper and Interface Generator
3.6.1. Resources
3.6.2. SWIG installation guide
4. Build Tool
4.1. Ant
4.1.1. Resources
4.1.2. Ant installation guide
4.2. Maven
4.2.1. Resources
4.2.2. Maven installation guide
4.2.3. Compiler profile
4.2.4. Password Encryption
4.2.5. Shell
5. Documentation
5.1. DocBook
5.1.1. Resources
5.1.2. XML Editor installation guide
6. Mail Server
6.1. Thunderbird
6.1.1. Resources
6.1.2. Thunderbird installation guide
6.2. Apache James
6.2.1. Resources
6.2.2. Apache James installation guide
6.2.3. Apache James configuration
6.2.4. Windows service
7. HTTP Server
7.1. Apache HTTP Server
7.1.1. Resources
7.1.2. Apache HTTP Server installation guide
7.1.3. Windows service
7.1.4. Apache HTTP Server access
7.1.5. Home page
7.1.6. Manual activation
7.1.7. Virtual hosting configuration
7.1.8. Module mod_macro configuration
7.1.9. Proxy configuration
7.1.10. Module mod_wsgi configuration
7.1.11. Module mod_perl configuration
7.1.12. Module mod_dav configuration
7.1.13. Server info
8. Web Server
8.1. Tomcat
8.1.1. Resources
8.1.2. Tomcat installation guide
8.1.3. Windows service
8.1.4. Logging
8.1.5. Apache configuration
9. Application Server
9.1. GlassFish
9.1.1. Resources
9.1.2. GlassFish installation guide
9.1.3. Upgrade tool
9.1.4. Update tool
9.1.5. Changing JDK version
9.1.6. Autodeploy
9.1.7. Admin console
9.1.8. JVM switches for performance
9.1.9. Apache configuration
10. Database
10.1. MySQL
10.1.1. Resources
10.1.2. MySQL installation guide
10.1.3. Backup options
10.1.4. Replication
10.1.5. Upgrading
10.1.6. Maatkit
10.1.7. SQL Manager installation guide
10.1.8. Navicat installation guide
11. Version Control System
11.1. Git
11.1.1. Resources
11.1.2. Git installation guide
11.1.3. Test drive
11.1.4. Apache configuration
11.1.5. Defining a project
11.1.6. Working on a project
11.2. FishEye
11.2.1. Resources
11.2.2. FishEye installation guide
11.2.3. FishEye configuration
11.2.4. Apache configuration
11.2.5. Windows service
11.2.6. Database migration
12. Issue Tracker
12.1. JIRA
12.1.1. Resources
12.1.2. JIRA installation guide
12.1.3. JIRA configuration
12.1.4. Apache configuration
12.1.5. Windows service
13. Repository Manager
13.1. Nexus
13.1.1. Resources
13.1.2. Nexus installation guide
13.1.3. Windows service
13.1.4. Apache configuration
13.1.5. Nexus configuration
13.1.6. Maven integration
14. Continuous Integration
14.1. Jenkins
14.1.1. Resources
14.1.2. Jenkins installation guide
14.1.3. Apache configuration
14.1.4. Jenkins configuration
15. Integrated Development Environment
15.1. Eclipse
15.1.1. Resources
15.1.2. Eclipse installation guide
15.1.3. Eclipse configuration
15.1.4. Plugins installation guide
15.1.5. Plugins configuration
15.1.6. Team support
16. Project
16.1. Setup base components
16.1.1. Team Synchronizing Git
16.1.2. Project information
16.1.3. Environment
16.1.4. Site
16.1.5. Plugin Versions
16.1.6. Deployment
16.1.7. Java base POM
16.1.8. Continuous integration
16.1.9. Release
16.1.10. Versions
16.1.11. Application Integration overview
17. Quality Assurance
17.1. Maven reports
17.2. Sonar
17.2.1. Resources
17.2.2. Sonar installation guide
17.2.3. Upgrading
17.2.4. Sonar configuration
17.2.5. Apache configuration
17.2.6. Windows service
17.2.7. Maven integration
17.2.8. Jenkins integration
17.2.9. Maven vs Sonar Quality Assurance reports comparison
17.3. jDocBook
17.3.1. Docbook configuration
17.3.2. Documentation setup
17.3.3. Hyphenation
17.3.4. Publication
A. Tips & Tricks
A.1. Archives
A.1.1. How to extract content from MSI files
A.2. Eclipse
A.2.1. Patch, test and build an Eclipse plugin
A.2.2. Repository Browsing
A.3. Project
A.3.1. Custom skins
A.3.2. Quality Assurance Sandbox
B. Alternatives
B.1. Version Control System
B.1.1. Subversion (SVN)
B.1.2. Concurrent Versions System (CVS)
B.1.3. ViewVC
B.2. Issue Tracker
B.2.1. Bugzilla
C. End Of Life
C.1. Windows
C.1.1. Firewall
C.2. Maven
C.2.1. Maven CLI plugin
C.3. HTTP Server
C.3.1. Module mod_python
C.4. Version Control System
C.4.1. ViewVC installation guide with CvsGraph patch
D. Source

trickChapter 1. Operating System

trick1.1. Windows

Microsoft Windows 7 is an operating system for personal and business computers, including both desktops and laptops.

trick1.1.1. Resources

  • Leaving Microsoft to Change the World.

  • Sysinternals utilities to help manage, troubleshoot and diagnose your Windows systems and applications.

  • SharpKeys is a Registry hack that is used to make certain keys on a keyboard act like other keys. For example you could use this utility to map Caps Lock to a Left Shift.

  • The Windows 7 forum covers news and updates and has an extensive Windows 7 tutorial section that covers a wide range of tips and tricks.

  • A List of Run Commands for Windows 7.

  • Exploring Windows 7's New Search Features.

  • Netstat displays protocol statistics and current TCP/IP network connections.

  • PortQry is a command-line utility that you can use to help troubleshoot TCP/IP connectivity issues. The PortQueryUI tool provides a graphical user interface for the PortQry Command Line Port Scanner. New features and functionality in PortQry version 2.0.

  • NMAP (Network Mapper) is a free and open source utility for network exploration or security auditing. Many systems and network administrators also find it useful for tasks such as network inventory, managing service upgrade schedules, and monitoring host or service uptime.

  • trickThe Microsoft Microsoft Visual C++ 2010 Redistributable Package (x86) or (x64) installs runtime components of Visual C++ Libraries required to run applications developed with Visual C++ on a computer that does not have Visual C++ 2010 installed.

  • Quick fix for disappearing system tray icons.

trick1.1.2. Desktop

To configure the Desktop minimize all open windows with +M and right click on the desktop Personalize it. This will open Control PanelAppearance and PersonalizationPersonalization where you can set Desktop Background, Window Color, Sounds and Screen Saver. After Save Changes also Save theme.

To add your own folders to the Picture location of the Windows Desktop Backgrounds create the following registry file P:\dev\apps\windows\registry\wallpapers.reg:

Windows Registry Editor Version 5.00

[HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer\Wallpapers\KnownFolders\0\Windows Wallpapers\MergeFolders]
"C:\\media\\gfx\\bball"=""
"C:\\media\\gfx\\cycling"=""
"C:\\media\\gfx\\minus\\eol\\removes\\entry"=-

Import these settings with regedit "P:\dev\apps\windows\registry\wallpapers.reg".

trick1.1.3. Explorer

Windows 7 introduces a brand new Windows Explorer which is superior in many ways to its predecessors. In Windows Explorer select OrganizeLayout to activate the Menu bar, Display pane and Navigation pane. In the Menu bar select ViewDetails

To configure the Windows Explorer first select the Local Disk (C:) and then OrganizeFolder and search options or ToolsFolder options... where you can set:

  • General:

    • Open each folder in the same window.

    • Double-click to open an item (single-click to select).

    • Show all folders.

    • Automatically expand to current folder.

  • View:

    • Always show menus.

    • Display file icon on thumbnails.

    • Display file size information in folder tips.

    • Show hidden files, folders, or drives.

    • Uncheck Hide extensions for known file types.

    • Uncheck Hide protected operating system files (Recommended).

    • Show drive letters.

    • Show encrypted or compressed NTFS folders in color.

    • Optionally uncheck Use Sharing Wizard (Recommended).

    • Select the typed item in the view

      and Apply to Folders.

  • Search:

    • In indexed locations, search file names and contents.

    • Include subfolders in search results when searching in file folders.

    • Find partial matches.

    • Include system directories.

Tip

Advanced search is available by holding down Windows Logo+F keys.

For every non system drive select it and then OrganizePropertiesCustomize (see also Customize Tab - Add or Remove from Properties) or ViewCustomize this folder... to Optimize this folder for General items, check Also apply this template to all subfolders and click OK.

trick1.1.4. Windows 7 Start Menu

First go to Start MenuControl PanelEase of AccessEase of Access CenterMake the keyboard easier to use and select Underline keyboard shortcuts and access keys.

To customize the Start Menu right click on the Taskbar and select Properties.

  • Taskbar

    • Check Lock the taskbar which is also available with right click on the Taskbar and select Properties.

    • Check Use small icons.

    • Taskbar buttons: Combine when taskbar is full.

    • Customize... which icons and notifications appear in the notification area.

    • Check Use Aero Peek to preview the desktop.

  • Start Menu

    • In Privacy disable Store and display recently opened programs in the Start menu and Store and display recently opened items in the Start menu and the taskbar.

    • Customize...

      • Computer: Display as a link.

      • Control Panel: Display as a link.

      • Uncheck Default Programs.

      • Check Devices and Printers.

      • Documents: Don't display this item.

      • Downloads: Don't display this item.

      • Check Enable context menus and dragging and dropping.

      • Uncheck Favorites menu.

      • Games: Don't display this item.

      • Uncheck Help.

      • Uncheck Highlight newly installed programs.

      • Uncheck Homegroup.

      • Music: Don't display this item.

      • Check Network.

      • Personal folder: Don't display this item.

      • Pictures: Don't display this item.

      • Uncheck Recent Items.

      • Recorded TV: Don't display this item.

      • Check Run command.

      • Search other files and libraries: Search without public folders.

      • Check Search programs and Control Panel.

      • Check Sort All Programs menu by name.

      • System administrative tools: Display on the All Programs menu and the Start menu.

      • Uncheck Use large icons.

      • Videos: Don't display this item.

  • Quick Launch Toolbar is restored with right click on the Taskbar and select ToolbarsNew toolbar... and point to Folder C:\Users\<username>\AppData\Roaming\Microsoft\Internet Explorer\Quick Launch. Right click on the Quick Launch Toolbar to uncheck Show Text and Show title.

trick1.1.5. Task Manager replacement

Process Explorer shows you information about which handles and DLLs processes have opened or loaded.

Download the archive: ProcessExplorer.zip [version 15.23].

Extract the .zip file to P:\dev\apps\windows\processexplorer. Start the Process Explorer with procexp.exe and select OptionsReplace Task Manager and OptionsHide When Minimized.

Create a shortcut Process Explorer for it in StartProgramsStartup to be able to access PropertiesRunMinimized to always start it in the system tray on startup.

Important

To be able to run the Process Explorer on startup the Windows 7 User Account Control (UAC) has to be turned off.

trick1.1.6. Symbolic links

Junction (also called a soft link) differs from a hard link in that the storage objects it references are separate directories, and a junction can link directories located on different local volumes on the same computer. Otherwise, junctions operate identically to hard links. Junctions are implemented through reparse points.

Download the archive: Junction.zip [version 1.06].

Extract the .zip file to C:\Windows\System32.

Verify the installation with junction.

trick1.1.7. User Account Control replacement

As a robust Security Monitor, WinPatrol will alert you to hijackings, malware attacks and critical changes made to your computer without your permission.

Download the binary: wpsetup.exe [version 25.6.2012.1].

Run this .exe file to install WinPatrol in P:\dev\apps\windows\winpatrol.

trick1.1.7.1. How to Disable and Turn Off UAC

Go to Start MenuControl PanelSystem and SecurityAction CenterChange User Account Control settings and slide the slider bar to Never notify. Click Ok and restart the computer to turn off User Access Control.

trick1.1.8. Windows Update

Go to Start MenuControl PanelSystem and SecurityWindows UpdateChange settings:

  • Important updates: Check for updates but let me choose whether to download and install them.

  • Recommended updates: Give me recommended updates the same way I receive important updates.

Important

Before upgrading to SP1 uninstall all language packs except the default with lpksetup to avoid error C000009A.

The System Update Readiness Tool for Windows 7 for x64-based Systems (KB947821) is being offered because an inconsistency was found in the Windows servicing store which may prevent the successful installation of future updates, service packs, and software.

trick1.1.9. Antivirus

All-inclusive and comprehensive protection avast! antivirus Home Edition includes ANTI-SPYWARE protection, certified by the West Coast Labs Checkmark process, and ANTI-ROOTKIT detection based on the best-in class GMER technology.

Download the binary: setup_av_free.exe [version 7.0.1474].

Run this .exe file to custom install avast! in P:\dev\apps\antivirus\avast. To skip the avast gadget installation select the option Custom and uncheck avast! gadget. Optionally uncheck the avast! Remote Assistance, a browser plugin for website reputation rating; a combination of data from their virus lab and community voting.

Tip

To uninstall it after an automatic upgrade run appwiz.cpl and right click on avast! to Uninstall/Change and Next uncheck the gadget.

Disable WebRep and Community settings with Open avast! user interfaceSettings:

  • Clouds Services: disable reputation services.

  • Community: disable participate in the avast! community.

Sometimes it´s not possible to uninstall avast! the standard way in the control panel. In this case, you can use our uninstallation utility aswClear.

Note

See also Apache James James.Mailet: RemoteDelivery issue.

trick1.1.10. Command Processor

To use the Tab for filename and directory name completion in the Command Processor create the following registry file P:\dev\apps\windows\registry\command processor.reg:

Windows Registry Editor Version 5.00

[HKEY_CURRENT_USER\Software\Microsoft\Command Processor]
"CompletionChar"=dword:00000009
"PathCompletionChar"=dword:00000009

Import these settings with regedit "P:\dev\apps\windows\registry\command processor.reg".

After starting the Command Processor configure the following settings by clicking Alt+Space and selecting Properties (for the Command Prompt shortcut in for example the Quick Launch Toolbar) and/or Defaults (for StartRun...cmd):

  • Options: in Command History enable Discard Old Duplicates and in Edit Options enable Quick Edit Mode and Insert Mode.

  • Font: Font Lucida Console with Size 16.

  • Layout: Screen Buffer Size Width 130 x Height 9999 and Window Size Width 130 x Height 59. Click Ok.

trick1.1.10.1. Batch files

trickPress Windows Logo+Break keys to open the Windows System Properties. Select Advanced system settingsEnvironment Variables and Edit the Path to append %BATCH_HOME%;. Also add a New system variable BATCH_HOME pointing to P:\dev\apps\windows\batch.

trick1.1.11. Services

The Service Control command (sc.exe) provided by Microsoft is a command line program used for communicating with the NT Service Controller and services. Some of the options are:

  • sc qc [service_name] queries the configuration information for a service.

  • sc start [service_name] starts a service.

  • sc query [service_name] queries the status for a service.

  • sc stop [service_name] sends a stop request to a service.

  • sc create service_name creates a service in the registry.

  • sc delete service_name deletes a service from the registry.

trickTo edit the Service properties launch the Service Management Console with services.msc.

trickIf a service fails to start check the Application Log in StartAdministrative ToolsEvent Viewer or launch the Event Viewer Console from the command line with eventvwr.msc and select Event Viewer (Local)Windows LogsApplication.

Note

If you see something like The description for Event ID ( 0 ) in Source ( ... ) cannot be found. ... You may be able to use the /AUXSOURCE= flag to retrieve this description; ... The following information is part of the event: ... it's Windows telling you that it can't find the template to nicely format the event content, so it'll give you the raw event data.

trick1.1.11.1. Delayed service loading

To make sure that for example the Database Service is available when the Application Server Service starts create a dependency between both services as follows:

  1. Start regedit.

  2. Select HKEY_LOCAL_MACHINESYSTEMCurrentControlSetservicesappserverService.

  3. Right click on appserverService and select NewMulti-String Value.

  4. Set the name to DependOnService.

  5. Right click on DependOnService and select Modify.

  6. Set the Value data to databaseService (in case of multiple services create a space separated list).

  7. Run: sc qc appserverService to verify the dependencies.

    Note

    In case of the following error: [SC] GetServiceConfig needs nnn bytes try sc qc appserverService <buffersize>, where the specified buffersize is equal or larger than the number of bytes in the error message.

For an alternative take a look at the manual Startup and Shutdown batch files.

trick1.1.11.2. Service Wrapper

WinSW (or GitHub) creates a wrapper executable that can be used to host any executable as a Windows Service with a less restrictive license than the Java Service Wrapper.

trickPress Windows Logo+Break keys to open the Windows System Properties. Select Advanced system settingsEnvironment Variables and Edit the Path to append %SERVICES_HOME%;. Also add a New system variable SERVICES_HOME pointing to P:\dev\apps\windows\services.

To configure any executable as a Windows Service create a service configuration file exampleService.xml in P:\dev\apps\windows\services:

<service>
  <id>example</id>
  <name>Example Service</name>
  <description>Sample service configuration.</description>
  <depend>Spooler</depend>
  <depend>Messenger</depend>
  <logpath>P:\dev\logs\windows\services</logpath>
  <logmode>roll</logmode>
  <env name="TMPDIR" value="C:\tmp" />
  <startargument>run</startargument>
  <stopargument>stop</stopargument>
  <argument>%TMPDIR%</argument>
  <executable>exampleApplication.exe</executable>
  <!--beeponshutdown/-->
  <!--waithint>20000</waithint-->
  <!--sleeptime>1000</sleeptime-->
</service>

Get a copy of the latest binary [version 1.9], rename it to exampleService.exe and place it next to the exampleService.xml in P:\dev\apps\windows\services.

Install the dummy service with exampleService install. Start it with exampleService start or sc start example. Other winsw options are status, stop and uninstall.

Verify the installation with services.msc and view the event logs with eventvwr.msc.

trick

Warning

Windows XP kills all services that take longer than the WaitToKillServiceTimeout registry setting (default is 20000 milliseconds) on shutdown. When experimenting with WinSW usage for MySQL this resulted in the following error message InnoDB: Database was not shut down normally!.

trick1.1.11.3. Startup and Shutdown batch files

To start and stop the services in a certain order make use of the net command instead of sc because this one waits for the service stopped signal (see also warning about WaitToKillServiceTimeout). For the things to come create the following two batch files P:\dev\apps\windows\batch\services-startup.bat:

net start james
net start mysqlmaster
net start mysqlslave
net start fisheye
net start jira
net start nexus
net start sonar
net start tomcat
net start glassfish

REM pause 10 seconds
ping -n 10 127.0.0.1  > NUL

and P:\dev\apps\windows\batch\services-shutdown.bat:

net stop glassfish
net stop tomcat
net stop sonar
net stop nexus
net stop jira
net stop fisheye
net stop mysqlslave
net stop mysqlmaster
net stop james

REM pause 10 seconds
ping -n 10 127.0.0.1  > NUL

trick1.1.12. Data Execution Prevention

Data Execution Prevention (DEP) is a set of hardware and software technologies that perform additional checks on memory to help prevent malicious code from running on a system.

When a program (for example java.exe version 1.3.1 update 20) won't start and displays the following error message To help protect your computer, Windows has closed this program., you can manually exclude the program from the DEP feature.

Press Windows Logo+Break keys to open the Windows System Properties. Select AdvancedSettingsData Execution PreventionTurn on DEP for all programs and services except those I select and Add... the program.

trick1.1.13. Archive Tools

A file archiver is a computer program that combines a number of files together into one archive file, or a series of archive file, for easier transportation or storage. Many file archivers employ archive formats that provide lossless data compression to reduce the size of the archive which is often useful for transferring a large number of individual files over a high latency network like the Internet.

trick1.1.13.1. WinRAR

WinRAR is a powerful archive manager.

Download the binary: winrar-x64-420.exe [version 4.20].

Run this .exe file to install WinRAR in P:\dev\apps\archive\winrar.

Configure OptionsSettings...ViewerExternal viewer name to point to for example P:\dev\apps\editor\ultraedit\Uedit32.exe. Use Ctrl+H to switch to and from Flat folders view.

trick1.1.13.2. 7-Zip

7-Zip is a file archiver with a high compression ratio.

Download the binary (MSI Installer): 7z920-x64.msi [version 9.20].

Run this .msi file to install 7-Zip in P:\dev\apps\archive\7zip.

trick1.1.13.3. HJ-Split

HJ-Split multi-platform file splitter and joiner.

Download the archive: hjsplit.zip [version 3.0].

Extract the .zip file to P:\dev\apps\archive\hjsplit.

trick1.1.14. GnuWin32

GnuWin32 provides ports of tools with a GNU or similar open source license to MS-Windows.

trickPress Windows Logo+Break keys to open the Windows System Properties. Select Advanced system settingsEnvironment Variables and Edit the Path to append %GNUWIN32_HOME%\bin;. Also add a New system variable GNUWIN32_HOME pointing to P:\dev\apps\gnuwin32.

trick1.1.14.1. DiffUtils

DiffUtils shows differences between files.

Download the Win32 binary: diffutils-2.8.7-1.exe [version 2.8.7.1].

Run this .exe file to install DiffUtils in P:\dev\apps\gnuwin32.

Verify the installation with diff -version.

trick1.1.14.2. Patch

Patch applies a diff file to an original.

Download the Win32 binary: patch-2.5.9-7-setup.exe [version 2.5.9.7].

Run this .exe file to install Patch in P:\dev\apps\gnuwin32.

Verify the installation with patch -version. Take a look at Section C.4.1, “ViewVC installation guide with CvsGraph patch” for usage of patch.

Important

If you run patch and get one of the following error messages: can't find file to patch at input line ... or Assertion failed: hunk, file ..., line ..., make sure the directory separator (for the entries: Index:, --- and +++) is the backslash (\) and not the forwardslash (/) and the file contains CR-LF as line endings instead of just LF.

trick1.1.14.3. LibIconv

LibIconv converts from one character encoding to another through Unicode conversion. It has also limited support for transliteration, i.e. when a character cannot be represented in the target character set, it is approximated through one or several similar looking characters.

Instead of the older binary libiconv-1.9.2-1.exe download the one maintained at ftp.zlatkovic.com (or mirror): iconv-1.9.2.win32.zip [version 1.9.2].

Extract this .zip file to C:\tmp and move the three subdirectories bin, include and lib to P:\dev\apps\gnuwin32.

Verify the installation with iconv --version.

trick1.1.14.4. ZLib

ZLib is designed to be a free, general-purpose, legally unencumbered -- that is, not covered by any patents -- lossless data-compression library for use on virtually any computer hardware and operating system. The zlib data format is itself portable across platforms.

Instead of the older binary zlib-1.2.3.exe download the one maintained at ftp.zlatkovic.com (or mirror): zlib-1.2.5.win32.zip [version 1.2.5].

Extract this .zip file to C:\tmp and move the three subdirectories bin, include and lib to P:\dev\apps\gnuwin32.

trick1.1.14.5. LibXml2

LibXml2 is the XML C parser and toolkit developed for the Gnome project, but usable outside of the Gnome platform.

Instead of the older archive libxml2-2.4.12-bin.zip download the one maintained at ftp.zlatkovic.com (or mirror): libxml2-2.7.8.win32.zip [version 2.7.8].

Extract this .zip file to C:\tmp and move the three subdirectories bin, include and lib to P:\dev\apps\gnuwin32.

Important

To upgrade the libxml2.dll you might need to stop the Apache HTTP Server.

Verify the installation with xmllint -version.

trick1.1.15. Text editor

A text editor is a type of program used for editing plain text files.

trick1.1.15.1. Notepad++

Notepad++ is a free (as in free speech and also as in free beer) source code editor and Notepad replacement that supports several languages.

Download the binary: npp.6.2.Installer.exe [version 6.2].

Run this .exe file to install Notepad++ in P:\dev\apps\editor\notepad++.

Notepad++ supports a few command line parameters to control its startup.

trick1.1.15.2. UltraEdit

UltraEdit is the ideal text, HTML and hex editor, and an advanced PHP, Perl, Java and JavaScript editor for programmers.

Download the archive: ue_english.zip [version 16.30.0.1003]* and any required dictionaries and manuals.

Extract the .zip file to C:\tmp. Run the MSI Installer ue_english.msi to custom install UltraEdit in P:\dev\apps\editor\ultraedit.

Install the dictionaries with the MSI Installer, for example Dutch.msi, in P:\dev\apps\editor\ultraedit\GNU\aspell.

trick1.1.16. Merging tool

Merging (also called integration) in revision control, is a fundamental operation that reconciles multiple changes made to a revision-controlled collection of files. Most often, it is necessary when a file is modified by two people on two different computers at the same time. When two branches are merged, the result is a single collection of files that contains both sets of changes.

trick1.1.16.1. KDiff3

KDiff3 compares or merges two or three text input files or directories.

Download the binary: KDiff3-32bit-Setup_0.9.97.exe [version 0.9.97].

Run this .exe file to install KDiff3 in P:\dev\apps\editor\kdiff3.

trick1.1.16.2. WinMerge

WinMerge is an Open Source differencing and merging tool for Windows. It can compare both folders and files, presenting differences in a visual text format that is easy to understand and handle. The WinMerge command line accepts several parameters in addition to the paths to compare.

Download the binary: WinMerge-2.12.4-Setup.exe [version 2.12.4].

Run this .exe file to install WinMerge in P:\dev\apps\editor\winmerge.

To configure an different external editor select EditOptions...System and change External editor in P:\dev\apps\editor\notepad++\notepad++.exe.

trick1.1.17. Secure Shell

Secure Shell or SSH is a network protocol that allows data to be exchanged using a secure channel between two networked devices.

trick1.1.17.1. PuTTY

PuTTY is a free implementation of Telnet and SSH for Win32 and Unix platforms, along with an xterm terminal emulator.

Download the binary: putty.exe [version 0.62].

Just copy this .exe file in P:\dev\apps\shell\putty.

trick1.1.17.1.1. Default Settings

To change PuTTY's default settings run PuTTY make the required changes and set Saved Sessions: Default Settings and click Save.

Tip

If you find your sessions are closing unexpectedly (most often with Connection reset by peer) after they have been idle for a while, you might want to try using the Connection option Seconds between keepalives (0 to turn off): 60.

In WindowAppearance Change... Font Lucida Console, Font Style Regular and Size 12.

trick1.1.18. File Transfer

File transfer is a generic term for the act of transmitting files over a computer network or the Internet. There are numerous ways and protocols to transfer files over a network. Computers which provide a file transfer service are often called file servers. Depending on the client's perspective the data transfer is called uploading or downloading.

trick1.1.18.1. WinSCP

WinSCP is an open source free SFTP client and FTP client for Windows. Legacy SCP protocol is also supported. Its main function is safe copying of files between a local and a remote computer.

Download the binary: winscp511setup.exe [version 5.1.1].

Run this .exe file to install WinSCP in P:\dev\apps\ftp\winscp.

trick1.1.18.2. All-in-one FTP/SFTP/HTTP/WebDAV Client

BitKinex integrates the functionality of an innovative FTP, SFTP and WebDAV client for Windows.

Download the binary: bitkinex323.exe [version 3.2.3].

Run this .exe file to install BitKinex in P:\dev\apps\ftp\bitkinex.

trick1.1.19. Graph Visualization Software

Graphviz is open source graph visualization software. Graph visualization is a way of representing structural information as diagrams of abstract graphs and networks. Automatic graph drawing has many important applications in software engineering, database and web design, networking, and in visual interfaces for many other domains.

Download the binary (MSI Installer): graphviz-2.28.0.msi [version 2.28.0].

Run this .msi file to install Graphviz in P:\dev\apps\editor\graphviz.

trickPress Windows Logo+Break keys to open the Windows System Properties. Select Advanced system settingsEnvironment Variables and Edit the Path to append %GRAPHVIZ_HOME%\bin;. Also add a New system variable GRAPHVIZ_HOME pointing to P:\dev\apps\editor\graphviz.

Verify the installation with dot -v and click Ctrl+C.

trick1.1.20. Debugging Tools

The Microsoft debuggers are fully capable of running on computers with x86-based, Itanium, or x64-based processors. The debuggers can debug the Windows operating system, applications, services, and drivers that run on the operating system.

Download the binary (MSI Installer): dbg_amd64_6.11.1.404.msi [version 6.11.1.404]*.

Run this .msi file to custom install four Microsoft debuggers WinDbg, KD, CDB, and NTSD in P:\dev\apps\windows\debugger.

Register WinDBG as the default handler for dump files with: P:\dev\apps\windows\debugger\windbg.exe -IA.

Start WinDBG without opening any dump files and set FileSymbol File Path... to SRV*P:\dev\data\windows\debugger\symbolcache*http://msdl.microsoft.com/download/symbols.

How to Analyse Bugcheck and Process Crash Dumps.

trick1.1.21. Viewers

A file viewer is application software that presents the data stored in a computer file in a human-friendly form.

trick1.1.21.1. Excel

Excel Viewer lets you view and print Microsoft Excel documents on a computer that does not have Excel installed.

Download the binary: ExcelViewer.exe and the following list of patches [version SP3].

Run this .exe file and patches to install Excel Viewer in P:\dev\apps\editor\excel.

trick1.1.21.2. Word

Word Viewer lets you view and print Microsoft Word documents on a computer that does not have Microsoft Word installed.

Download the binary: wordview_en-us.exe and the following list of patches [version KB2345009].

Run this .exe file to install Word Viewer in P:\dev\apps\editor\word.

trick1.1.21.3. PowerPoint

PowerPoint Viewer lets you view full-featured presentations created in PowerPoint 97 and later versions.

Download the binary: PowerPointViewer.exe and the following list of patches [version SP3].

Run this .exe file and patches to install Excel Viewer in P:\dev\apps\editor\powerpoint.

trick1.1.21.4. Foxit PDF Reader

Foxit Reader is a free PDF document viewer, with incredible small size, breezing-fast launch speed and rich feature set.

Download the binary: FoxitReader514.0104_enu_Setup.exe [version 5.1.4.0104].

Run this .exe file to custom install Foxit Reader in P:\dev\apps\editor\foxit.

Note

Skip installation of the Foxit Search Bar powered by Ask.

Enable/disable the Safe Reading Mode after installation in ToolsPreferences...Trust Manager.

trick1.1.22. Utilities

There are some excellent free software utilities available that are every bit as good as their commercial counterparts, and sometimes even better. One software publisher, with an almost unknown name, but with very popular products is Piriform Software.

trick1.1.22.1. Recuva

Accidentally deleted an important file? Lost something important when your computer crashed? No problem! Recuva recovers files deleted from your Windows computer, Recycle Bin, digital camera card, or MP3 player.

Download the binary: rcsetup143.exe [version 1.43.623].

Run this .exe file to install Recuva in P:\dev\apps\windows\recuva.

trick1.1.22.2. CCleaner

CCleaner is a system optimization, privacy and cleaning tool. It removes unused files from your system - allowing Windows to run faster and freeing up valuable hard disk space. It also cleans traces of your online activities such as your Internet history. Additionally it contains a fully featured registry cleaner.

Download the binary: ccsetup324.exe [version 3.24.1850].

Run this .exe file to install CCleaner in P:\dev\apps\windows\ccleaner.

trick1.1.22.3. Defraggler

Use Defraggler to defrag your entire hard drive, or individual files - unique in the industry.

Download the binary: dfsetup211.exe [version 2.11.560].

Run this .exe file to install Defraggler in P:\dev\apps\windows\defraggler.

trick1.1.22.4. Speccy

Speccy is an advanced System Information tool for your PC.

Download the binary: spsetup118.exe [version 1.18.379].

Run this .exe file to install Defraggler in P:\dev\apps\windows\speccy.

trick1.1.22.5. Resource Hacker

Resource Hacker is a utility to view, modify, rename, add, delete and extract resources in 32bit Windows executables and resource files.

Download the archive: reshack_setup.exe [version 3.6.0.92].

Extract the .zip file to P:\dev\apps\windows\resourcehacker.

trickChapter 2. Browser

trick2.1. Firefox

Firefox the Web browser from Mozilla.

trick2.1.1. Resources

  • Download a Firefox version that speaks your language.

  • The Mozilla Developer Center (MDC) supports the growth and development of Firefox and the web by providing comprehensive, accurate, and up-to-date documentation and news about Firefox and web development technologies.

  • mozillaZine is an independent Mozilla news, community and advocacy site.

  • LifeHacker tips & downloads for getting things done.

  • Add-ons extend Firefox, letting you personalize your browsing experience:

    • FT SleekDark is a dark blue theme for Firefox.

    • FT GraphiteGlow is a smooth graphite theme for Firefox.

    • Mac OSX is an Mac style theme.

    • XUL/Migemo is a more customizable Find Toolbar with dictionary-assisted find and a highlight feature (Safari style).

      • XUL/Migemo is the dictionary-assisted find for Japanese (or other languages). Download the xulmigemodic.zip dictionary for manual installation at P:\dev\data\browser\firefox\add-ons\migemo\dict. When Firefox restarts select Choose Existing Dictionary to find the manual installed one and check Never show this wizard.

    • NoScript allows JavaScript and Java execution only for trusted domains of your choice (e.g. your home-banking web site). NoScript optionally blocks Flash and other potentially exploitable plugins too, and provides the most powerful Anti-XSS protection available in a browser.

    • IE Tab Plus is an enhanced version of IE Tab with Adblock Plus in IE supported. It also allows you import settings from IE Tab and synchronize cookies between IE and Firefox.

    • Status-4-Evar to restore Status Bar in Firefox 4.

    • StatusbarEx to show some useful system information on the addon bar of Firefox, such as the memory usage of system & Firefox itself and network speed.

    • Download Manager Tweak allows the download manager to also open in a tab or sidebar, and adds some optional display changes.

    • DownThemAll is all you can desire from a download manager: it features an advanced accelerator that increases speed up to 400% and it allows you to pause and resume downloads at any time.

    • FlashGot is meant to handle single and massive downloads with several external Download Managers. In Firefox select ToolsFlashGotMore Options... and in GeneralDownload ManagerDTA to use DownThemAll.

    • DownloadHelper is a tool for web content extraction. Its purpose is to capture video and image files from many sites.

    • PrefBar along with the standard preference checkboxes, the new version includes utility buttons, user agent spoofing, web links, and more, served on a fully customizable toolbar with a side of white rice. It's even possible to use PrefBar to create macro buttons to run nearly any code you want.

    • Firebug integrates with Firefox to put a wealth of web development tools at your fingertips while you browse. You can edit, debug, and monitor CSS, HTML, and JavaScript live in any web page. Useful extensions:

      • Page Speed is an open-source project started at Google to help developers optimize their web pages by applying web performance best practices.

      • YSlow analyzes web pages and tells you why they're slow based on Yahoo's rules for high performance web sites.

      • Firecookie makes possible to view and manage cookies in your browser.

    • LiveHTTPHeaders displays HTTP headers in real time and lets you edit request headers and replay an URL.

    • Linkification converts text links into genuine, clickable links.

    • Linky will increase your power to handle links. It will let you open or download all or selected links, image links and even web addresses found in the text in separate tabs or windows.

    • LinkChecker checks webpage links at a glance with simple color coding.

    • User Agent Switcher adds a menu and a toolbar button to switch the user agent of a browser.

    • Vacuum Places Improved defragments your Firefox Places database (history/bookmarks). This greatly reduces the lag while typing in the address bar and the start-up time.

    • Adobe Flash Player is a cross-platform browser-based application runtime that delivers uncompromised viewing of expressive applications, content, and videos across screens and browsers. If you are having problems uninstalling Flash Player on Windows, follow those steps.

trick2.1.2. Firefox installation guide

Download the Win32 binary: Firefox Setup 16.0.2.exe [version 16.0.2].

Run this .exe file to custom install Firefox in P:\dev\apps\browser\firefox.

Optionally install useful extensions and pimp the browser theme for example with the the above mentioned add-ons. Speaking of add-ons toggle the Add-on Bar with Ctrl+/. Now right click on this bar to uncheck Tabs on Top and reactivate the Menu Bar.

trick2.1.2.1. Custom profile folder

Mozilla Firefox stores all your personal settings, such as bookmarks, passwords and extensions, in a profile folder.

To move it to a new location, all you have to do is close Firefox and move the default profile folder 2 and set the absolute path 1 for the new location 3 in %APPDATA%\Mozilla\Firefox\profiles.ini:

[General]
StartWithLastProfile=1

[Profile0]
Name=default
IsRelative=1trick10
Path=Profiles/xxxxxxxx.defaulttrick2P:\dev\data\browser\firefox\profiles\defaulttrick3

trick2.1.3. Firefox preferences

To display a list of used preferences, as well as a search bar, type about:config (see also About protocol) in the Firefox address bar:

browser.cache.disk.parent_directory

To specify in which folder the Cache is stored, add a NewString preference browser.cache.disk.parent_directory, and set the value to C:\tmp\firefox. The Cache directory location can be viewed with about:cache.

browser.cache.disk.capacity

Set the preference maximum amount of hard drive space in KB to use for cache.

browser.cache.memory.capacity

Add a NewInteger preference browser.cache.memory.capacity to control the maximum amount of memory to use for caching decoded images and chrome (application user interface elements). For RAM sizes 8 GB and up defaults to 32768.

browser.tabs.closeButtons

The preference controls how the close button for tabs is displayed. The value 3 displays a single close button at the end of the tab strip.

Tip

A handy keyboard shortcut for undoing accidentally closed tabs is Ctrl+Shift+T and accidentally closed windows is Ctrl+Shift+N .

network.prefetch-next

To stop Firefox from silently prefetching hinted documents set the preference to false.

browser.sessionhistory.max_total_viewer

Disable the Back-Forward Cache that retains the rendered document for the last five session history entries for each tab by setting the preference to 0.

browser.sessionhistory.max_entries

Reduce the maximum number of pages in the browser's session history Back-Forward Cache by setting the preference to 10.

Note

The saving of tabs when quitting Firefox 4 has been disabled by default. To (re)activate all warning dialogs enable the following 4 settings and reset the last one:

browser.showQuitWarning

To restore the Quit Dialog: Save and Quit, Quit or Cancel set the preference to true. Unless browser.startup.page is 3 (see also below).

browser.tabs.warnOnClose

To restore the Confirm Close Dialog: Close tabs or Cancel set the preference to true.

browser.warnOnQuit

To restore the Exit Dialog: Save and Quit, Quit or Cancel set the preference to true.

browser.warnOnRestart

To restore the Restart Dialog: Restart or Cancel set the preference to true.

browser.startup.page

Each time the web browser starts, this preference is consulted to determine what to display. It has superseded browser.sessionstore.resume_session as the preference determining whether saved sessions are restored. The value 3 resumes the previous browser session.

trick2.2. Safari

Safari renders web pages at lightning speed. It works on your iPad, iPhone, iPod touch, Mac, and PC.

trick2.2.1. Resources

  • Download a Safari version for Mac and PC.

  • Learn about the innovative features available in Safari.

  • Safari Extensions are a great way for you to add new features to Safari. Built by developers, Safari Extensions use the latest HTML5, CSS3, and JavaScript web technologies. They're digitally signed and sandboxed for improved security. You can install extensions with one click — no need to restart Safari.

trick2.2.2. Safari installation guide

Download the Win32 binary: SafariSetup.exe [version 5.1.2].

Run this .exe file to custom install Safari in P:\dev\apps\browser\safari.

trick2.3. Chrome

Chrome runs websites and applications with lightning speed.

trick2.3.1. Resources

  • Download a Chrome version.

  • Chrome has many useful features built in, including translation in the browser, apps, extensions, themes, and more.

  • Chrome Web Store is an online marketplace where you can discover thousands of apps, extensions and themes for Google Chrome.

trick2.3.2. Chrome installation guide

Download the Win32 binary: ChromeSetup.exe for the Google Chrome Web Browser only [version 16.0.912.75].

To simulate custom installation of Chrome in P:\dev\apps\browser\google create a symbolic link using Junction as follows:

mkdir P:\dev\apps\browser\chrome
mkdir %LOCALAPPDATA%\Google

junction %LOCALAPPDATA%\Google\Chrome P:\dev\apps\browser\chrome
junction -s %LOCALAPPDATA%\Google

Run this .exe file to install Chrome.

trickChapter 3. Programming Languages

trick3.1. Java 2 Platform

Java Platform, Standard Edition (a.k.a. Java 2 Platform) lets you develop and deploy Java applications on desktops and servers, as well as today's demanding Embedded and Real-Time environments. Java SE includes classes that support the development of Java Web Services and provides the foundation for Java Platform, Enterprise Edition (Java EE).

trick3.1.1. Resources

trick3.1.2. JDK installation guide

Download the Win32 binary: jdk-7u9-windows-i586.exe [version 1.7.0_09].

Run this .exe file to install the JDK Development Tools with Change... into P:\dev\apps\prg\java\jdk1.7.0_09. After the JDK is installed Change... the JRE Destination Folder into P:\dev\apps\prg\java\jre1.7.0_09.

trickPress Windows Logo+Break keys to open the Windows System Properties. Select Advanced system settingsEnvironment Variables and Edit the Path to append %JAVA_HOME%\bin;. Also add a New system variable JAVA_HOME pointing to P:\dev\apps\prg\java\jdk1.7.0_09.

Verify the installation with java -version.

Tip

If you want to be able to run different versions of java by changing the JAVA_HOME and the Path settings make sure there are no files installed at dir %SystemRoot%\System32\java*.*. If there are, just delete the files java.exe, javaw.exe and javaws.exe. Keep the file javacpl.cpl to start the Java Control Panel and on the Java tab View... which JREs are enabled.

Warning

Old %SystemRoot%\SysWow64\java*.* files can cause the following error Registry key 'Software\JavaSoft\Java Runtime Environment\CurrentVersion' has value '1.6', but '1.5' is required..

Note

If you also install the older JDK versions 1.4 and 1.3 (see also Section 1.1.12, “Data Execution Prevention”) and you don't want to use the default directories make sure that you right click on Public JRE to select Don't install this feature for now. Because it isn't possible to change the default directory for the included JRE. Install those JREs with their separate install file.

trick3.2. C#

Visual C# 2010 Express is the ideal tool for productively building object-oriented applications for Windows on the .NET Framework.

Download the Win32 binary: vcs_web.exe [version 10.0.30319.1].

Run this .exe file to install it for from the Internet. Install without the optional products into a new destination folder P:\dev\apps\prg\visualstudio.2010.

trick3.3. C++

Visual C++ 2010 Express provides a powerful and flexible development environment for creating native Windows and cool 2D and 3D games.

Download the Win32 binary: vc_web.exe [version 10.0.30319.1].

Run this .exe file to install it for from the Internet. Install without the optional products into the destination folder P:\dev\apps\prg\visualstudio.2010.

Run P:\dev\apps\prg\visualstudio.2010\VC\bin\vcvars32.bat from the command line to set environment for using Microsoft Visual Studio 2010 x86 tools. Verify the settings with make /?.

Note

Alas to build Python bindings for Subversion on Win32 yourself Python 2.7 needs Visual Studio 2008. Install without the optional products into the destination folder P:\dev\apps\prg\visualstudio.2008.

trick3.4. Python

Python is a dynamic object-oriented programming language that can be used for many kinds of software development. It offers strong support for integration with other languages and tools, comes with extensive standard libraries, and can be learned in a few days. Many Python programmers report substantial productivity gains and feel the language encourages the development of higher quality, more maintainable code. Fans of Python use the phrase batteries included to describe the standard library, which covers everything from asynchronous processing to zip files.

trick3.4.1. Resources

trick3.4.2. Python installation guide

Download the Win32 binary (MSI Installer): python-2.7.3.msi [version 2.7.3].

Run this .msi file to install it for all users. Install all the features into a new destination folder P:\dev\apps\prg\python-2.7.3.

trickPress Windows Logo+Break keys to open the Windows System Properties. Select Advanced system settingsEnvironment Variables and Edit the Path to append %PYTHON_HOME%;. Also add a New system variable PYTHON_HOME pointing to P:\dev\apps\prg\python-2.7.3 and reboot the server.

Verify the installation with python --version.

Download the Python for Windows Extensions Win32 binary: pywin32-218.win32-py2.7.exe [version 218].

From the command line run this .exe file to install the Windows extensions in P:\dev\apps\prg\python-2.7.3.

Important

Run the application from the command line to avoid the error message close failed in file object destructor: Error in sys.excepthook:.

trick3.4.3. Python Enterprise Application Kit

PEAK is the Python Enterprise Application Kit. If you develop enterprise applications with Python, or indeed almost any sort of application with Python, PEAK may help you do it faster, easier, on a larger scale, and with fewer defects than ever before. The key is component-based development, on a reliable infrastructure.

Easy Install is a python module (easy_install) bundled with setuptools that lets you automatically download, build, install, and manage Python packages.

trick3.4.3.1. Setuptools installation guide

Download the Win32 binary: setuptools-0.6c11.win32-py2.7.exe [version 0.6.c11].

Run this .exe file to install it into P:\dev\apps\prg\python-2.7.3.

Press Windows Logo+Break keys to open the Windows System Properties. Select Advanced system settingsEnvironment Variables and Edit the Path to append %PYTHON_HOME%\Scripts;.

Verify the installation with easy_install -h.

trick3.4.4. Pygments

Pygments is a generic syntax highlighter for general use in all kinds of software such as forum systems, wikis or other applications (such as ViewVC) that need to prettify source code.

trick3.4.4.1. Pygments installation guide

Just run easy_install -i http://pypi.python.org/simple/ Pygments [version 1.5].

trick3.5. Perl

Perl is a dynamic programming language created by Larry Wall and first released in 1987. Perl borrows features from a variety of other languages including C, shell scripting (sh), AWK, sed and Lisp. Perl was widely adopted for its strengths in text processing and lack of the arbitrary limitations of many scripting languages at the time.

trick3.5.1. Resources

trick3.5.2. Perl installation guide

Download the Win32 Binary (MSI Installer): ActivePerl-5.12.4.1205-MSWin32-x86-294981.msi [version 5.12.4.1205]*.

Important

Don't use the 64-bit version because then mod_perl can't be found in http://cpan.uwinnipeg.ca/PPMPackages/12xx/.

Run this .msi file to install it for all users. Install all the features into a new destination folder P:\dev\apps\prg\perl-5.12.4.1205 and do not add Perl to the Path environment variable.

Important

Installing Perl into a directory that contains a space (e.g. C:\Program Files) will break the Template-Toolkit installer.

trickPress Windows Logo+Break keys to open the Windows System Properties. Select Advanced system settingsEnvironment Variables and Edit the Path to append %PERL_HOME%\site\bin;%PERL_HOME%\bin;. Also add a New system variable PERL_HOME pointing to P:\dev\apps\prg\perl-5.12.4.1205 and reboot the server.

Verify the installation with perl -V.

trick3.5.3. Perl Package Manager user guide

Start the Perl Package Manager with: ppm gui.

Switch to ViewInstalled Packages or Ctrl+2 and select FileVerify Packages to check for updates.

Switch to ViewUpgradable Packages or Ctrl+3. If the column Repo is not shown select ViewView ColumnRepo to activate it. To upgrade the package from the original repository just right click on it and select Install ... or +. Should there be a higher version of the package available in a different repository right click on the installed package and select Remove ... or - and then right click on the latest version of that package and select Install ... or +.

After selecting the packages that must be upgraded switch to ViewPackages to Install/Remove or Ctrl+4 and select FileRun Marked Actions or Ctrl+Enter to update.

Tip

Run ppm upgrade to check for available upgrades.

trick3.5.3.1. Module DBI

The Perl DBI module provides a generic interface for database access. You can write a DBI script that works with many different database engines without change. To use DBI, you must install the DBI module, as well as a DataBase Driver (DBD) module for each type of server you want to access. For MySQL, this driver is the DBD::mysql module.

For the DBI add uwinnipeg Perl 5.12 repository with ppm repo add uwinnipeg-5.12xx http://cpan.uwinnipeg.ca/PPMPackages/12xx/. Also run ppm repo add bribes-5.12xx http://www.bribes.org/perl/ppm/ and ppm repo add trouchelle-5.12xx http://trouchelle.com/ppm12/.

Verify the repository installations with ppm repo list or start the ppm gui Perl Package Manager and look at the available repositories with EditPreferences or Ctrl+P and Repositories.

Install the DBI module inclusive the MySQL implementation with ppm install DBI [version 1.616] and ppm install DBD::mysql [version 4.018].

trick3.5.3.2. Module PerlMagick

PerlMagick is an objected-oriented Perl interface to ImageMagick. Use the module to read, manipulate, or write an image or image sequence from within a Perl script. This makes it very suitable for Web CGI scripts such as Bugzilla.

ImageMagick is a software suite to create, edit, and compose bitmap images. It can read, convert and write images in a variety of formats (over 100) including DPX, EXR, GIF, JPEG, JPEG-2000, PDF, PhotoCD, PNG, Postscript, SVG, and TIFF. Use ImageMagick to translate, flip, mirror, rotate, scale, shear and transform images, adjust image colors, apply various special effects, or draw text, lines, polygons, ellipses and Bézier curves.

Download the Win32 Binary: ImageMagick-6.7.4-7-Q16-windows-dll.exe [version 6.7.4-7].

Run this .exe file to install ImageMagick into the following folder P:\dev\apps\gfx\imagemagick and select the following additional tasks:

  • Install PerlMagick for ActiveState Perl v5.12.4 build 1205.

trickPress Windows Logo+Break keys to open the Windows System Properties. Select Advanced system settingsEnvironment Variables and Edit the Path to append %IMAGEMAGICK_HOME%;. Also add a New system variable IMAGEMAGICK_HOME pointing to P:\dev\apps\gfx\imagemagick and reboot the server.

Important

Because C:\Windows\System32 also contains a convert.exe file, which is used to convert a FAT volume to NTFS, place %IMAGEMAGICK_HOME%; before it in the Path.

Verify the installation with convert -version or convert logo: c:\tmp\logo.gif followed by identify c:\tmp\logo.gif.

An example of the convert command to reduce the image size before it is written to the PNG format: convert c:\tmp\logo.gif -resize 50% c:\tmp\logo.png.

trick3.5.3.2.1. PDF issue

After resizing a PNG for usage with the Maven jDocBook Plugin to generate a PDF, one might run into the following error situation:

java.lang.NullPointerException: Parameter alpha must not be null
        at org.apache.fop.pdf.AlphaRasterImage.<init>(AlphaRasterImage.java:57)
        at org.apache.fop.pdf.AlphaRasterImage.<init>(AlphaRasterImage.java:71)
        at org.apache.fop.render.pdf.ImageRenderedAdapter.setup(ImageRenderedAdapter.java:125)
        at org.apache.fop.pdf.PDFDocument.addImage(PDFDocument.java:809)
        at            ...              handleImage(PDFImageHandlerRenderedImage.java:79)

Just remove the transparency from the PNG with the option -flatten, for example: convert 235283-32.png -flatten -resize 50% status4evar.png.

trick3.6. Simplified Wrapper and Interface Generator

SWIG is an interface compiler that connects programs written in C and C++ with scripting languages such as Perl, Python, Ruby, and Tcl. It works by taking the declarations found in C/C++ header files and using them to generate the wrapper code that scripting languages need to access the underlying C/C++ code.

trick3.6.1. Resources

trick3.6.2. SWIG installation guide

Download the archive: swigwin-2.0.4.zip [version 2.0.4].

Extract this .zip file to P:\dev\apps\prg.

Verify the installation with P:\dev\apps\prg\swigwin-2.0.4\swig.exe --version.

trickChapter 4. Build Tool

trick4.1. Ant

Apache Ant is a Java-based build tool. In theory, it is kind of like Make, but without Make's wrinkles.

trick4.1.1. Resources

trick4.1.2. Ant installation guide

Download the archive: apache-ant-1.8.4-bin.zip [version 1.8.4].

Extract this .zip file to P:\dev\apps\build.

trickPress Windows Logo+Break keys to open the Windows System Properties. Select Advanced system settingsEnvironment Variables and Edit the Path to append %ANT_HOME%\bin;. Also add a New system variable ANT_HOME pointing to P:\dev\apps\build\apache-ant-1.8.4.

Verify the installation with ant -version.

trick4.2. Maven

Maven is a software project management and comprehension tool. Based on the concept of a project object model (POM), Maven can manage a project's build, reporting and documentation from a central piece of information.

trick4.2.2. Maven installation guide

Download the archive: apache-maven-3.0.4-bin.zip [version 3.0.4].

Extract this .zip file to P:\dev\apps\build.

trickPress Windows Logo+Break keys to open the Windows System Properties. Select Advanced system settingsEnvironment Variables and Edit the Path to append %M2_HOME%\bin;. Also add a New system variable M2_HOME pointing to P:\dev\apps\build\apache-maven-3.0.4.

The location of your local repository 1 can be changed in the Maven configuration file P:\dev\apps\build\apache-maven-3.0.4\conf\settings.xml:

<?xml version="1.0" encoding="UTF-8"?>

<settings xmlns="http://maven.apache.org/settings/1.0.0" 
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
          ...>
  <!-- localRepository
   | The path to the local repository maven will use to store artifacts.
   |
   | Default: ~/.m2/repository
  <localRepository>/path/to/local/repo</localRepository>
  -->
  <localRepository>P:/dev/data/repo/maven/local</localRepository>trick1

trickPress Windows Logo+Break keys to open the Windows System Properties. Select Advanced system settingsEnvironment Variables and supply extra options to Maven with a New system variable MAVEN_OPTS and for example the following value -XX:MaxPermSize=192m -Xmx512m -Xms128m.

trick

Important

JDK 7 brings support for IPv6 on Windows. If you attempt to connect to an IPv4 address then under the covers it will use an IPv4-mapped IPv6 address. This might cause an org.apache.maven.lifecycle.LifecycleExecutionException with Connection timed out: connect. Then add -Djava.net.preferIPv4Stack=true also to the MAVEN_OPTS.

Verify the installation with mvn -version.

trick4.2.3. Compiler profile

Configure Maven with the locations of all available java compilers using a compiler profile in the Maven configuration file P:\dev\apps\build\apache-maven-3.0.4\conf\settings.xml (see also Maven Shell settings):

  <profiles>
    <profile>
      <id>compiler</id>
      <activation>
        <activeByDefault>true</activeByDefault>
      </activation>
      <properties>
        <jdk.1.3.home>P:\dev\apps\prg\java\jdk1.3.1_20</jdk.1.3.home>
        <jdk.1.3.jvm>${jdk.1.3.home}\bin\java.exe</jdk.1.3.jvm>
        <jdk.1.3.javac>${jdk.1.3.home}\bin\javac.exe</jdk.1.3.javac>
        <jdk.1.3.javadoc>${jdk.1.3.home}\bin\javadoc.exe</jdk.1.3.javadoc>

        <jdk.1.4.home>P:\dev\apps\prg\java\jdk1.4.2_19</jdk.1.4.home>
        <jdk.1.4.jvm>${jdk.1.4.home}\bin\java.exe</jdk.1.4.jvm>
        <jdk.1.4.javac>${jdk.1.4.home}\bin\javac.exe</jdk.1.4.javac>
        <jdk.1.4.javadoc>${jdk.1.4.home}\bin\javadoc.exe</jdk.1.4.javadoc>

        <jdk.1.5.home>P:\dev\apps\prg\java\jdk1.5.0_22</jdk.1.5.home>
        <jdk.1.5.jvm>${jdk.1.5.home}\bin\java.exe</jdk.1.5.jvm>
        <jdk.1.5.javac>${jdk.1.5.home}\bin\javac.exe</jdk.1.5.javac>
        <jdk.1.5.javadoc>${jdk.1.5.home}\bin\javadoc.exe</jdk.1.5.javadoc>

        <jdk.1.6.home>P:\dev\apps\prg\java\jdk1.6.0_37</jdk.1.6.home>
        <jdk.1.6.jvm>${jdk.1.6.home}\bin\java.exe</jdk.1.6.jvm>
        <jdk.1.6.javac>${jdk.1.6.home}\bin\javac.exe</jdk.1.6.javac>
        <jdk.1.6.javadoc>${jdk.1.6.home}\bin\javadoc.exe</jdk.1.6.javadoc>

        <jdk.1.7.home>P:\dev\apps\prg\java\jdk1.7.0_09</jdk.1.7.home>
        <jdk.1.7.jvm>${jdk.1.7.home}\bin\java.exe</jdk.1.7.jvm>
        <jdk.1.7.javac>${jdk.1.7.home}\bin\javac.exe</jdk.1.7.javac>
        <jdk.1.7.javadoc>${jdk.1.7.home}\bin\javadoc.exe</jdk.1.7.javadoc>
      </properties>
    </profile>
  </profiles>

trick4.2.4. Password Encryption

Maven 2.1.0+ now supports server password encryption.

Create an encrypted master password with mvn --encrypt-master-password password and save it 1 in the file %USERPROFILE%\.m2\settings-security.xml:

<?xml version="1.0" encoding="UTF-8"?>

<settingsSecurity>
  <master>{encrypted master-password}trick1</master>
</settingsSecurity>

Now encrypt for example the nexus-releases server password 1 with mvn --encrypt-password password and place it in the Maven configuration file P:\dev\apps\build\apache-maven-3.0.4\conf\settings.xml:

  <servers>
    <server>
      <id>nexus-releases</id>
      <username>deployment</username>
      <password>{encrypted password}trick1</password>
    </server>
  </servers>

trick4.2.5. Shell

Maven Shell is a CLI interface for Apache Maven that enabled faster turn-around, and a more intelligent interaction with repositories and projects. Using Maven Shell, you will be able to speed up your builds because project information and Maven plugins are loaded into a single, always-ready JVM instance which can execute a Maven build.

Download the archive: mvnsh-assembly-1.0.1-bin.zip [version 1.0.1].

Extract this .zip file to P:\dev\apps\build.

trickPress Windows Logo+Break keys to open the Windows System Properties. Select Advanced system settingsEnvironment Variables and Edit the Path to append %SHELL_HOME%\bin;. Also add a New system variable SHELL_HOME pointing to P:\dev\apps\build\mvnsh-1.0.1.

Verify the installation with mvnsh -version.

Warning

Alas sometimes the error ComponentLookupException: NoSuchElementException prevents consecutive mvn commands (should be fixed in version 1.0.2).

trick4.2.5.1. Settings

Reuse the Maven installation settings:

copy p:\dev\apps\build\apache-maven-3.0.4\conf\settings.xml ^
     p:\dev\apps\build\mvnsh-1.0.1\conf

trick4.2.5.2. Colorized Maven output

ANSI color is supported on windows with the optional JNA dependency. To activate run install-jna once and restart as follows:

mvnsh
mvnsh(/):~> install-jna
mvnsh(/):~> exit

trickChapter 5. Documentation

trick5.1. DocBook

DocBook is a schema (available in several languages including RELAX NG, SGML and XML DTDs, and W3C XML Schema) maintained by the DocBook Technical Committee of OASIS . It is particularly well suited to books and papers about computer hardware and software (though it is by no means limited to these applications).

trick5.1.1. Resources

trick5.1.2. XML Editor installation guide

XMLmind XML Editor allows to author large, complex, modular, XML documents. It makes it easy mastering XML vocabularies such as DocBook or DITA.

Download the Win32 binary: xxe-perso-5_1_1-setup-nojvm.exe or xxe-eval-5_4_1-setup-nojvm.exe [version 5.4.1].

Run this .exe file to install XMLMind XML Editor in P:\dev\apps\editor\xmlmind.

Start the editor and select OptionsPreferences... to edit the following options:

  • ToolsValidate and check Automatically show Validity tool.

  • Window and check Show both tree and styled views.

    Reopen your document or restart the editor for these changes to take effect.

Tip

To move the Search and Validity tools to the top next to the Edit tool, activate it and move the mouse cursor towards the tear-off line until the cursor changes into , then just right click. This way the Attributes tool is better accessible in combination with search and validity actions.

trickChapter 6. Mail Server

trick6.1. Thunderbird

Reclaim your inbox with Mozilla's email application Thunderbird.

trick6.1.1. Resources

  • Download a fully localized version.

  • Thunderbird features many enhancements to help you better manage your unruly inbox, and stay informed.

  • Add-ons extend Thunderbird, letting you personalize your email client:

    • TT DeepDark is a smooth dark theme for Thunderbird.

    • Contacts Sidebar displays the address books in a sidebar in Thunderbirds 3-pane-window and can be toggled with the F4 key or a toolbar button.

trick6.1.2. Thunderbird installation guide

Download the Win32 binary: Thunderbird Setup 16.0.2.exe [version 16.0.2].

Run this .exe file to install Thunderbird in P:\dev\apps\mail\thunderbird.

Optionally install useful extensions and pimp the email client theme for example with the the above mentioned addons.

trick6.1.2.1. Custom profile folder

Mozilla Thunderbird stores all your personal settings, such as your mail, passwords and extensions, in a profile folder.

To move it to a new location, all you have to do is close Thunderbird and move the default profile folder 2 and set the absolute path 1 for the new location 3 in %APPDATA%\Thunderbird\profiles.ini:

[General]
StartWithLastProfile=1

[Profile0]
Name=default
IsRelative=1trick10
Path=Profiles/....defaulttrick2P:\dev\data\mail\thunderbird\profiles\defaulttrick3

trick6.2. Apache James

The Apache Java Enterprise Mail Server (a.k.a. Apache James) is a 100% pure Java SMTP and POP3 Mail server and NNTP News server.

trick6.2.1. Resources

trick6.2.2. Apache James installation guide

Download the archive: apache-james-2.3.2.zip [version 2.3.2].

Extract this .zip file to P:\dev\apps\mail.

trickPress Windows Logo+Break keys to open the Windows System Properties. Select Advanced system settingsEnvironment Variables and add a New system variable JAMES_HOME pointing to P:\dev\apps\mail\james-2.3.2.

trick6.2.3. Apache James configuration

To get the configuration files extracted to P:\dev\apps\mail\james-2.3.2\apps\james\conf and P:\dev\apps\mail\james-2.3.2\apps\james\SAR-INF start the server with the following command %JAMES_HOME%\bin\run.bat. Terminate the server with Ctrl+C.

trick6.2.3.1. Host configuration

In C:\WINDOWS\system32\drivers\etc\hosts file on the Mail Server computer add the following host mapping 1:

# Copyright (c) 1993-2009 Microsoft Corp.
#
# This is a sample HOSTS file used by Microsoft TCP/IP for Windows.
#
# This file contains the mappings of IP addresses to host names. Each
# entry should be kept on an individual line. The IP address should
# be placed in the first column followed by the corresponding host name.
# The IP address and the host name should be separated by at least one
# space.
#
# Additionally, comments (such as these) may be inserted on individual
# lines or following the machine name denoted by a '#' symbol.

# localhost name resolution is handled within DNS itself.
# 127.0.0.1       localhost
# ::1             localhost

127.0.0.1    mail.dev.nettrick1

trick6.2.3.2. Global server configuration

Edit the following settings 1-4 in P:\dev\apps\mail\james-2.3.2\apps\james\SAR-INF\config.xml:

   <James>
      <postmaster>james.postmaster@company.orgtrick1</postmaster>
      <servernames autodetect="false"trick2 autodetectIP="false"trick3>
         <servername>mail.dev.nettrick4</servername>
      </servernames>
      <usernames ignoreCase="true" enableAliases="true" enableForwarding="true"/>
      <inboxRepository>
         <repository destinationURL="file://var/mail/inboxes/" type="MAIL"/>
      </inboxRepository>
   </James>

trick6.2.3.3. DNS configuration

Edit the following settings 1-2 in P:\dev\apps\mail\james-2.3.2\apps\james\SAR-INF\config.xml:

   <dnsserver>
      <servers>
        <server>IP address of DNS Servertrick1</server>
      </servers>
      <autodiscover>falsetrick2</autodiscover>
      <authoritative>false</authoritative>

      <!-- Maximum number of entries to maintain in the DNS cache -->
      <maxcachesize>50000</maxcachesize>
   </dnsserver>

Tip

To find the DNS server, type: ipconfig /all.

trick6.2.3.4. Remote Manager configuration

Edit the following settings 1-5 and uncomment the prompt setting 6 in P:\dev\apps\mail\james-2.3.2\apps\james\SAR-INF\config.xml:

   <remotemanager enabled="true">
      <port>4555</port>
      <bind>127.0.0.1</bind>trick1
      <handler>
         <helloName autodetect="false"trick2>mail.dev.nettrick3</helloName>
         <administrator_accounts>
            <account login="admin"trick4 password="password"trick5/>
         </administrator_accounts>
         <connectiontimeout> 60000 </connectiontimeout>
         <prompt>james&gt;</prompt>trick6
      </handler>
   </remotemanager>

Important

After the Mail Server is restarted access to the Remote Administration Tool should now only possible with telnet 127.0.0.1 4555 and the new username and password. Type shutdown to kill the current JVM (convenient when James is run as a daemon) or type quit to close the connection.

trick6.2.3.4.1. PuTTY configuration

Run PuTTY and configure the following custom Session:

  • Host Name: mail.dev.net.

  • Telnet.

  • Port: 4555.

  • ConnectionTelnetTelnet negotiation mode: Passive.

In Session set Saved Sessions: mail.dev.net remote manager and click Save and Open. Login with admin. Type quit to exit.

trick6.2.3.5. SMTP configuration

Edit the following settings 1-3 in P:\dev\apps\mail\james-2.3.2\apps\james\SAR-INF\config.xml:

   <smtpserver enabled="true">
      <!-- port 25 is the well-known/IANA registered port for SMTP -->
      <port>25</port>
      <bind>127.0.0.1</bind>trick1
      <handler>
         <helloName autodetect="false"trick2>mail.dev.nettrick3</helloName>
         <connectiontimeout>360000</connectiontimeout>
         <authorizedAddresses>127.0.0.0/8</authorizedAddresses>
         <maxmessagesize>0</maxmessagesize>
      </handler>
   </smtpserver>

After the Mail Server is restarted verify the connection with telnet 127.0.0.1 25. When all goes well the response will be: 220 mail.dev.net SMTP Server (JAMES SMTP Server 2.3.1) ready.... Type quit to close the connection.

Tip

When telnet is Connecting To 127.0.0.1... and reports the following error Could not open connection to the host, on port 25: Connect failed use for example the PortQueryUI tool (see also features and functionality) to get additional information with the command portqry.exe -n 127.0.0.1 -e 25 -p TCP. In case of Error opening socket: 10053 A Winsock error has been encountered. A firewall or a virus scanner is probably blocking the port.

Important

In case the INFO message James.Mailet: RemoteDelivery: Could not connect to SMTP host: ..., port: 25, response: 421 and the virus scanner is avast! select Open avast! user interfaceREAL-TIME SHIELDSMail Shield to disable Scan outbound messages.

trick6.2.3.5.1. PuTTY configuration

Run PuTTY and configure the following custom Session:

  • Host Name: mail.dev.net.

  • Telnet.

  • Port: 25.

  • ConnectionTelnetTelnet negotiation mode: Passive.

In Session set Saved Sessions: mail.dev.net telnet and click Save and Open. Type quit to exit.

trick6.2.3.6. POP3 configuration

Disable the following setting 1 in P:\dev\apps\mail\james-2.3.2\apps\james\SAR-INF\config.xml:

   <pop3server enabled="false"trick1>
      <!-- port 995 is the well-known/IANA registered port for POP3S -->
      <!-- port 110 is the well-known/IANA registered port for Standard POP3 -->
      <port>110</port>

      <handler>
         <helloName autodetect="false"trick2>mail.dev.nettrick3</helloName>
         <connectiontimeout>120000</connectiontimeout>
      </handler>
   </pop3server>

trick6.2.3.7. NNTP configuration

Disable the following settings 1 and 4 in P:\dev\apps\mail\james-2.3.2\apps\james\SAR-INF\config.xml:

    <!-- NNTP-specific: if you disable the NNTP Server, 
         you should also set the nntp-repository's threadCount to 0, 
         otherwise there will be threads active and polling  -->
   <nntpserver enabled="false"trick1>
      <!-- port 563 is the well-known/IANA registered port for NNTP SSL/TLS -->
      <!-- port 119 is the well-known/IANA registered port for Standard NNTP -->
      <port>119</port>

      <handler>
         <helloName autodetect="false"trick2>mail.dev.nettrick3</helloName>
         <connectiontimeout>120000</connectiontimeout>
         <authRequired>false</authRequired>
      </handler>
   </nntpserver>

   <nntp-repository>
      ...

      <spool>
         <configuration>
            <spoolPath>file://var/nntp/spool</spoolPath>
            <threadCount>1trick40</threadCount>
            <threadIdleTime>60000</threadIdleTime>
         </configuration>
      </spool>
   </nntp-repository>

trick6.2.3.8. Transport processor configuration

In case of a Microsoft Exhange Server edit the following settings 1-2 in P:\dev\apps\mail\james-2.3.2\apps\james\SAR-INF\config.xml:

      <processor name="transport">
         ...

         <mailet match="All" class="RemoteDelivery">
            ...
   
            <gateway>IP address of Microsoft Exhange Server</gateway>trick1
            <gatewayPort>25</gatewayPort>trick2
         </mailet>
      </processor>

trick6.2.3.9. Data storage

For the ease of future upgrades replace file://var/ with file:///P:/dev/data/mail/james/ for the following file locations in P:\dev\apps\mail\james-2.3.2\apps\james\SAR-INF\config.xml:

  1. /mail/inboxes/

  2. /mail/error/

  3. /mail/outgoing/

  4. /mail/spam/

  5. /mail/address-error/

  6. /mail/relay-denied/

  7. /nntp/groups

  8. /nntp/temp

  9. /nntp/articleid

  10. /nntp/spool

  11. /mail/spool/

  12. /dbmail (2x)

  13. /users/

The old now unused location P:\dev\apps\mail\james-2.3.2\apps\james\var and its subdirectories can be deleted.

Logging can be found in P:\dev\apps\mail\james-2.3.2\logs and P:\dev\apps\mail\james-2.3.2\apps\james\logs.

trick6.2.4. Windows service

To restart automatically on Microsoft Windows, create a Windows service. Use the Tanuki Java Service Wrapper shipped with James.

Optionally edit the following entries 1-4 in the service wrapper configuration file P:\dev\apps\mail\james-2.3.2\conf\wrapper.conf:

# Wrapper Windows Properties
wrapper.console.title=James Mail Server 2.3.2dev.net Apache Jamestrick1

...

# Wrapper Windows NT/2000/XP Service Properties
wrapper.ntservice.name=James 2.3.2jamestrick2
wrapper.ntservice.displayname=James Mail Server 2.3.2dev.net Apache Jamestrick3
wrapper.ntservice.description=James Mail Server 2.3.2The Java Apache Mail Enterprise Server.trick4

Register the Apache James service with the command: %JAMES_HOME%\bin\Wrapper.exe -i %JAMES_HOME%\conf\wrapper.conf.

Start Apache James with net start james.

Important

In case of the following error Startup failed: Timed out waiting for a signal from the JVM when using jdk 1.7, just use jdk 1.6 instead 1 in P:\dev\apps\mail\james-2.3.2\conf\wrapper.conf:

# Java Application
wrapper.java.command=P:\dev\apps\prg\java\jdk1.6.0_37\bin\javatrick1

trickChapter 7. HTTP Server

trick7.1. Apache HTTP Server

The Apache HTTP Server Project is an effort to develop and maintain an open-source HTTP server for modern operating systems including UNIX and Windows NT. The goal of this project is to provide a secure, efficient and extensible server that provides HTTP services in sync with the current HTTP standards.

trick7.1.1. Resources

trick7.1.2. Apache HTTP Server installation guide

Download the Win32 binary (MSI Installer): httpd-2.2.21-win32-x86-no_ssl.msi [version 2.2.21].

Run this .msi file.

Important

In case of an upgrade you must deinstall the old version first. Before you deinstall make a copy of the apache_2.2.x directory structure. Because although most configuration files and changed modules will remain on disk after deinstallation but some directories will be deleted completely such as htdocs.

The installation will ask you for the following information:

  • Network Domain: dev.net (or localhost).

  • Server Name: dev.net (or localhost).

  • Administrator's Email Address: http.admin@company.org.

  • Install Apache HTTP Server 2.2 programs and shortcuts for: select only for the Current User, on Port 8080, when started Manually and click Next.

  • Please select a setup type: Typical for everything except the source code and libraries for module development and click Next.

  • Destinantion folder: Change... it into P:\dev\apps\httpserver\apache-2.2.21. Click Next and Install.

trickPress Windows Logo+Break keys to open the Windows System Properties. Select Advanced system settingsEnvironment Variables and Edit the Path to append %APACHE_HOME%\bin;. Also add a New system variable APACHE_HOME pointing to P:\dev\apps\httpserver\apache-2.2.21 .

Verify the installation with httpd -V.

trick7.1.3. Windows service

To restart automatically on Microsoft Windows listening on port 80 1 instead of 8080 edit the configuration file P:\dev\apps\httpserver\apache-2.2.21\conf\httpd.conf:

#
# Listen: Allows you to bind Apache to specific IP addresses and/or
# ports, instead of the default. See also the <VirtualHost>
# directive.
#
# Change this to Listen on specific IP addresses as shown below to 
# prevent Apache from glomming onto all bound IP addresses.
#
#Listen 12.34.56.78:80
Listen 8080trick1

Install the service with httpd -k install -n "dev.net Apache HTTP" (with service name dev.netApacheHTTP) and start it with httpd -k start -n "dev.net Apache HTTP".

Note

In case of an upgrade uninstall the existing service, which is referencing the prior version, with httpd -k uninstall -n "dev.net Apache HTTP" first.

After the service is started verify the installation in your browser at http://localhost.

When the Apache HTTP Service is running, you can see the Apache Service Monitor icon in the system tray. Right click on this icon and select Open Apache Monitor to activate the console in which the Apache HTTP Server can be (re)started and stopped.

trick7.1.4. Apache HTTP Server access

Allow controls which hosts can access an area of the server. Block Internet access by commenting the following entries 1 and 2 in the two non default Directory elements of P:\dev\apps\httpserver\apache-2.2.21\conf\httpd.conf:

#
# This should be changed to whatever you set DocumentRoot to.
#
<Directory "P:/dev/apps/httpserver/apache-2.2.21/htdocs">
    ...

    #
    # Controls who can get stuff from this server.
    #
#trick1   Order allow,deny
#trick2    Allow from all
</Directory>

...

#
# "P:/dev/apps/httpserver/apache-2.2.21/cgi-bin" should be changed to whatever
# your ScriptAliased CGI directory exists, if you have that configured.
#
<Directory "P:/dev/apps/httpserver/apache-2.2.21/cgi-bin">
    AllowOverride None
    Options None
#trick1    Order allow,deny
#trick2    Allow from all
</Directory>

In the default Directory element replace the Order 1 and Deny 2 by a reference to the httpd-access.conf 3 with the default behavior 4 for the interaction between host-level access control and user authentication:

# First, we configure the "default" to be a very restrictive set of 
# features.  
#
<Directory />
    Options FollowSymLinks
    AllowOverride None
    Order deny,allowtrick1
    Deny from alltrick2

    Include ../apache-conf/httpd-access.conftrick3
    Satisfy alltrick4
</Directory>

Create P:\dev\apps\httpserver\apache-conf\httpd-access.conf to allow access from the local area network 2 and localhost 1:

    Order allow,deny
    Allow from 127.0.0.1 # Localhosttrick1
    Allow from 192.168.0 # Local area network partial IP rangetrick2

trick7.1.4.1. Authentication, authorization and access control

Authentication is any process by which you verify that someone is who they claim they are. Authorization is any process by which someone is allowed to be where they want to go, or to have information that they want to have. Access Control refers to any means of controlling access to any resource. Access control can be done by several different modules. The most important of these is mod_authz_host.

Create a batch file P:\dev\apps\windows\batch\http-add-user.bat:

if exist P:\dev\data\httpserver\security\http-users-dev.net 
  goto addUser

md P:\dev\data\httpserver\security
htpasswd -c P:\dev\data\httpserver\security\http-users-dev.net %1

goto end
  
:addUser  
htpasswd C:\dev\data\www\httpserver\security\http-users-dev.net %1

:end

Warning

Option -c creates a new file.

Create the first user and the password file P:\dev\data\httpserver\security\http-users-dev.net with the command: http-add-user jjasper. And all consecutive users with the commands: http-add-user maven, http-add-user fisheye, http-add-user jira, http-add-user jenkins and http-add-user sonar.

Setup the user's level of access to the repository path: either r (read-only) or rw (read-write) in the file P:\dev\data\httpserver\security\http-access-dev.net:

[/]
jjasper = rw
maven = r
fisheye = r
jira = r
jenkins = r
sonar = r

trick7.1.4.2. Realm

Create the realm configuration file P:\dev\apps\httpserver\apache-conf\httpd-realm.conf:

    Require valid-user
    AuthType Basic
    AuthName "dev.net Realm"
    AuthUserFile "P:/dev/data/httpserver/security/http-users-dev.net"

trick7.1.5. Home page

Make the dev.net Home page content upgrade safe by changing the following two settings 1 and 2 in P:\dev\apps\httpserver\apache-2.2.21\conf\httpd.conf:

#
# DocumentRoot: The directory out of which you will serve your
# documents. By default, all requests are taken from this directory, but
# symbolic links and aliases may be used to point to other locations.
#
DocumentRoot "P:/dev/apps/httpserver/apache-2.2.21/htdocsP:/dev/data/httpserver/hometrick1"

...

#
# This should be changed to whatever you set DocumentRoot to.
#
<Directory "P:/dev/apps/httpserver/apache-2.2.21/htdocsP:/dev/data/httpserver/hometrick2">
    ...

    #
    # Controls who can get stuff from this server.
    #
#    Order allow,deny
#    Allow from all
</Directory>

Copy the content of P:\dev\apps\httpserver\apache-2.2.21\htdocs to trickP:\dev\data\httpserver\home as a starting point or create your own index.html which redirects to http://dev.net/mvn-sites/maven-setup (see also Section 16.1.2, “Project information”).

<html>
<head>
  <title>dev.net</title>
  <meta http-equiv="refresh" content="15;URL=http://dev.net/mvn-sites/maven-setup/" />
</head>

<body>
  <p>Redirecting to <a href="http://dev.net/mvn-sites/maven-setup/">http://dev.net/mvn-sites/maven-setup/</a>.</p>
</body>
</html>

After the Apache HTTP Server is restarted verify the installation in your browser at http://localhost.

trick7.1.6. Manual activation

To activate the local copy of the Apache HTTP Server Manual just uncomment the following line 1 in P:\dev\apps\httpserver\apache-2.2.21\conf\httpd.conf:

# Local access to the Apache HTTP Server Manual
trick1Include conf/extra/httpd-manual.conf

Block Internet access to the manual by commenting the following entries 1 and 2 in P:\dev\apps\httpserver\apache-2.2.21\conf\extra\httpd-manual.conf:

<Directory "P:/dev/apps/httpserver/apache-2.2.21/manual">
    Options Indexes
    AllowOverride None
#trick1    Order allow,deny
#trick2    Allow from all

After the Apache HTTP Server is restarted verify the installation in your browser at http://localhost/manual.

trick7.1.7. Virtual hosting configuration

The term Virtual Host refers to the practice of running more than one web site on a single machine.

To activate additional dev.net configuration add the following line 1 in P:\dev\apps\httpserver\apache-2.2.21\conf\httpd.conf:

# Virtual hosts
#Include conf/extra/httpd-vhosts.conf

# Reusable config for upgrades
Include ../apache-conf/httpd.conftrick1

Create P:\dev\apps\httpserver\apache-conf\httpd.conf with the following initial dev.net configuration 1:

# Virtual hosts
Include ../apache-conf/httpd-vhosts.conftrick1

Create P:\dev\apps\httpserver\apache-conf\httpd-vhosts.conf with the following default dev.net virtual host 2-5 on port 80 1:

NameVirtualHost *:80trick1

<VirtualHost *:80trick1>
    ServerAdmin http.webmaster@company.orgtrick2
    ServerName dev.nettrick3
    ErrorLog "P:/dev/logs/httpserver/dev.net-error.log"trick4
#    CustomLog "P:/dev/logs/httpserver/dev.net-access.log" commontrick5
</VirtualHost>

Make sure the directory P:\dev\logs\httpserver exists. Also create P:\dev\apps\httpserver\apache-conf\modules for storing third-party modules.

trickIn C:\WINDOWS\system32\drivers\etc\hosts file add the following mapping (on all developer PCs that want to access http://dev.net on the above configured host PC1):

#
# This file contains the mappings of IP addresses to host names. Each
# entry should be kept on an individual line. The IP address should
# be placed in the first column followed by the corresponding host name.
# The IP address and the host name should be separated by at least one
# space.
#
# Additionally, comments (such as these) may be inserted on individual
# lines or following the machine name denoted by a '#' symbol.

127.0.0.1    localhost
127.0.0.1    mail.dev.net
192.168.0.xx dev.nettrick1
192.168.0.xx www.dev.net

Important

Check if your browser is using a proxy. In Firefox select ToolsOptions...AdvancedNetworkSettings.... If this is the case add the following entries to No proxy for: localhost, 127.0.0.1, dev.net, 192.168.0.0/16.

trickFor future reference press Windows Logo+Break keys to open the Windows System Properties. Select Advanced system settingsEnvironment Variables and add a New system variable DEVNET_HOST_IP indicating the 192.168.0.xx host.

After the Apache HTTP Server is restarted verify the installation of the virtual host in your browser at http://dev.net. You should be able to see the dev.net Home page index.html.

trick7.1.8. Module mod_macro configuration

Mod_macro allows the definition and use of macros within apache runtime configuration files.

From Apache Lounge download the archive mod_macro-1.1.11-w32.zip [version 1.1.11].

Extract this .zip file to C:\tmp and move the file mod_macro.so to P:\dev\apps\httpserver\apache-conf\modules.

Include 1 the Macro module configuration at the top in P:\dev\apps\httpserver\apache-conf\httpd.conf:

# Apache Macro
Include ../apache-conf/httpd-macro.conftrick1

# Virtual hosts
Include ../apache-conf/httpd-vhosts.conf

with the following content in P:\dev\apps\httpserver\apache-conf\httpd-macro.conf:

LoadModule macro_module P:/dev/apps/httpserver/apache-conf/modules/mod_macro.so

For a sample use of mod_macro within a configuration file see Section 11.1.4, “Apache configuration” of the Git repositories.

trick7.1.9. Proxy configuration

A proxy server sits between a client application, such as a Web browser, and a real server. It intercepts all requests to the real server to see if it can fulfill the requests itself. If not, it forwards the request to the real server.

In the P:\dev\apps\httpserver\apache-conf\httpd-vhosts.conf file before the VirtualHost settings from Section 7.1.7, “Virtual hosting configuration” insert the following two modules 1 and 2:

LoadModule proxy_module modules/mod_proxy.sotrick1
LoadModule proxy_http_module modules/mod_proxy_http.sotrick2
#
# VirtualHost:

In the P:\dev\apps\httpserver\apache-conf\httpd-vhosts.conf file at the end of the VirtualHost settings from Section 7.1.7, “Virtual hosting configuration” add the following proxy configuration 1-6:

#
# VirtualHost:
# Almost any Apache directive may go into a VirtualHost container.
# The first VirtualHost section is used for all requests that do not
# match a ServerName or ServerAlias in any <VirtualHost> block.
#
<VirtualHost *:80>
    ServerAdmin http.webmaster@company.org
    ServerName dev.net
    ErrorLog "P:/dev/logs/httpserver/dev.net-error.log"
#    CustomLog "P:/dev/logs/httpserver/dev.net-access.log" common

    <IfModule proxy_module>trick1
    <IfModule proxy_http_module>trick2
        ProxyRequests Offtrick3
        ProxyPreserveHost Ontrick4

        <Proxy *>trick5
            Include ../apache-conf/httpd-access.conftrick6
        </Proxy>trick5
    </IfModule>trick2
    </IfModule>trick1
</VirtualHost>

The actual proxied servers includes will be supplied in the following chapters (for an example see Section 7.1.9.1.1, “Module mod_proxy_ajp configuration”).

trick7.1.9.1. Apache JServ Protocol

Apache JServ Protocol version 1.3 (hereafter ajp13) is packet-oriented. A binary format was presumably chosen over the more readable plain text for reasons of performance. The web server communicates with the servlet container over TCP connections. To cut down on the expensive process of socket creation, the web server will attempt to maintain persistent TCP connections to the servlet container, and to reuse a connection for multiple request/response cycles.

Once a connection is assigned to a particular request, it will not be used for any others until the request-handling cycle has terminated. In other words, requests are not multiplexed over connections. This makes for much simpler code at either end of the connection, although it does cause more connections to be open at once.

If AJP is to be used, the then mod_proxy_ajp module is preferred over mod_jk.

trick7.1.9.1.1. Module mod_proxy_ajp configuration

Mod_proxy_ajp is the AJP support module for mod_proxy.

In the P:\dev\apps\httpserver\apache-conf\httpd-vhosts.conf file before the VirtualHost settings from Section 7.1.7, “Virtual hosting configuration” append the following module 1:

LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_http_module modules/mod_proxy_http.so
LoadModule proxy_ajp_module modules/mod_proxy_ajp.sotrick1
#
# VirtualHost:

And then for example instruct Apache to proxy all URLs whose path portions begin with /http-sample/ and /ajp-sample/ using the following P:\dev\apps\httpserver\apache-conf\httpd-vhosts.conf include 1:

<VirtualHost *:80>
    ...

    <IfModule proxy_module>
    <IfModule proxy_http_module>
        ...

        <Proxy *>
            ...
        </Proxy>

        # Sample
        Include ../apache-conf/httpd-sample.conftrick1
    </IfModule>
    </IfModule>
</VirtualHost>

with the following content in P:\dev\apps\httpserver\apache-conf\httpd-sample.conf:

<IfModule proxy_module>
<IfModule proxy_http_module>
<IfModule proxy_ajp_module>
    <Location /http-sample>
        Include ../apache-conf/httpd-realm.conf  
    </Location>

    ProxyPass /http-sample          http://localhost:8068/http-sample
    ProxyPassReverse /http-sample   http://localhost:8068/http-sample

    <Location /ajp-sample>
        Include ../apache-conf/httpd-realm.conf  
    </Location>

    ProxyPass /ajp-sample          ajp://localhost:8069/ajp-sample
    ProxyPassReverse /ajp-sample   ajp://localhost:8069/ajp-sample
</IfModule>
</IfModule>
</IfModule>

Pre-packaged sample applications http-sample.war and ajp-sample.war can be downloaded for deployment in the installed Tomcat.

After the Apache HTTP Server is restarted verify the installation of the sample proxies in your browser at http://dev.net/http-sample and http://dev.net/ajp-sample.

Important

For this to work all URL references need to be relative.

trick7.1.9.1.2. Module mod_jk configuration

Mod_jk is the Apache Tomcat Connector based on the ajp1.3.

Download the Apache Tomcat Connector archive: tomcat-connectors-1.2.32-windows-i386-httpd-2.2.x.zip [version 1.2.32].

Extract the module to mod_jk.so from the downloaded archive and place it in P:\dev\apps\httpserver\apache-conf\modules.

Include 1 the Apache Tomcat Connector module configuration just before httpd-vhosts.conf in P:\dev\apps\httpserver\apache-conf\httpd.conf:

# Apache Tomcat Connector
Include ../apache-conf/httpd-jk.conftrick1

# Virtual hosts
Include ../apache-conf/httpd-vhosts.conf

with the following content in P:\dev\apps\httpserver\apache-conf\httpd-jk.conf:

LoadModule jk_module P:/dev/apps/httpserver/apache-conf/modules/mod_jk.so

<IfModule mod_jk.c>
    JkWorkersFile ../apache-conf/jk-workers.properties
    JkLogFile "P:/dev/logs/httpserver/dev.net-mod_jk.log"
    JkLogLevel info
    JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "
</IfModule>

Create the above referenced P:\dev\apps\httpserver\apache-conf\jk-workers.properties file:

worker.list=workerSample, fisheye

worker.workerSample.type=ajp13
worker.workerSample.host=localhost
worker.workerSample.port=8069

worker.fisheye.type=ajp13
worker.fisheye.host=localhost
worker.fisheye.port=8061

Extend the P:\dev\apps\httpserver\apache-conf\httpd-sample.conf from Section 7.1.9.1.1, “Module mod_proxy_ajp configuration” to mount /jk-sample 1:

<IfModule proxy_module>
<IfModule proxy_http_module>
<IfModule proxy_ajp_module>
    ...

    <Location /jk-sample>
        Include ../apache-conf/httpd-realm.conf  
    </Location>

    <IfModule mod_jk.c>
        JkMount /jk-sample   workerSampletrick1
        JkMount /jk-sample/* workerSampletrick1
    </IfModule>
</IfModule>
</IfModule>
</IfModule>

A pre-packaged sample application jk-sample.war can be downloaded for deployment in the installed Tomcat.

After the Apache HTTP Server is restarted verify the installation of the sample proxy in your browser at http://dev.net/jk-sample.

Important

For this to work all URL references need to be relative.

trick7.1.9.2. Html rewrite configuration

For some proxies it might be necessary to additionally configure the mod_proxy_html output filter to rewrite HTML links to ensure that links work for users outside the proxy.

Make sure to install the following four components vcredist_x86.exe or C++ development environment itself, zlib1.dll, libiconv2.dll and libxml2.dll.

From Apache Lounge download the archive mod_proxy_html-3.1.2-w32.zip [version 3.1.2].

Extract this .zip file to C:\tmp and move the files mod_proxy_html.so and mod_xml2enc.so to P:\dev\apps\httpserver\apache-conf\modules. Rename proxy_html.conf to httpd-proxy-html.conf and place it in P:\dev\apps\httpserver\apache-conf. In this last file P:\dev\apps\httpserver\apache-conf\httpd-proxy-html.conf load the files 1-3 and the modules 4-5:

# Configuration example.
  ...
# For Windows (I don't know if there's a standard path for the libraries)
trick1LoadFile "P:/dev/apps/gnuwin32/bin/zlib1.dll"
trick2LoadFile "P:/dev/apps/gnuwin32/bin/libiconv2.dll"
trick3LoadFile "P:/dev/apps/gnuwin32/bin/libxml2.dll"
trick4LoadModule proxy_html_module P:/dev/apps/httpserver/apache-conf/modules/mod_proxy_html.so
trick5LoadModule xml2enc_module P:/dev/apps/httpserver/apache-conf/modules/mod_xml2enc.so

...

# To support scripting events (with ProxyHTMLExtended On),
# you'll need to declare them too.

ProxyHTMLEvents onclick ondblclick onmousedown onmouseup \
                onmouseover onmousemove onmouseout onkeypress \
                onkeydown onkeyup onfocus onblur onload \
                onunload onsubmit onreset onselect onchange

Activate the extra required module 1 in P:\dev\apps\httpserver\apache-conf\httpd-proxy-html.conf:

LoadModule proxy_html_module P:/dev/apps/httpserver/apache-conf/modules/mod_proxy_html.so
LoadModule xml2enc_module    P:/dev/apps/httpserver/apache-conf/modules/mod_xml2enc.so
LoadModule headers_module modules/mod_headers.sotrick1

And include 1 the html rewriting configuration just before httpd-vhosts.conf in P:\dev\apps\httpserver\apache-conf\httpd.conf:

# Html rewriting
Include ../apache-conf/httpd-proxy-html.conftrick1

# Virtual hosts
Include ../apache-conf/httpd-vhosts.conf

For sample usage take a look at Section 8.1.5, “Apache configuration”.

Important

Although the context URI doesn't have to match the proxied application context URI anymore, it is still necessary, that all URL references are relative as you can see at http://dev.net/tomcat/http-sample/. Also notice the influence of the other ProxyPass /http-sample ... configuration on the one for ProxyPass /tomcat/ ... when the relative URI doesn't end in a slash /http-sample as in relative URL http sample 1 versus relative URL http sample 2.

trick7.1.10. Module mod_wsgi configuration

Mod_wsgi aims to implement a simple to use Apache module which can host any Python application which supports the Python WSGI interface. The module would be suitable for use in hosting high performance production web sites, as well as your average self managed personal sites running on web hosting services.

Download the Windows binary: mod_wsgi-win32-ap22py27-3.3.so [version 3.3].

Rename this module to mod_wsgi.so and place it in P:\dev\apps\httpserver\apache-conf\modules.

Include 1 this Python module just before httpd-vhosts.conf in P:\dev\apps\httpserver\apache-conf\httpd.conf:

# Python
Include ../apache-conf/httpd-python.conftrick1

# Virtual hosts
Include ../apache-conf/httpd-vhosts.conf

with the following content in P:\dev\apps\httpserver\apache-conf\httpd-python.conf:

# Python
LoadModule wsgi_module P:/dev/apps/httpserver/apache-conf/modules/mod_wsgi.so

<IfModule mod_wsgi.c>
    <Location /python-status>
        Order deny,allow
        Deny from all
        Allow from 127.0.0.1
    </Location>
</IfModule>

# Python Sample
Include ../apache-conf/httpd-python-sample.conf

Create the following file P:\dev\apps\httpserver\sample\python\status.wsgi:

import pprint

def application(environ, start_response):
    """ Display the contents of the environ dictionary."""
    # produce some content
    output =  pprint.pformat(environ)

    # send first header and status
    status = '200 OK'
    headers = [('Content-type', 'text/plain'),('Content-Length', str(len(output)))]
    start_response(status, headers)

    return [output]

Map this WSGI script in P:\dev\apps\httpserver\apache-conf\httpd-python-sample.conf:

WSGIScriptAlias /python-status P:/dev/apps/httpserver/sample/python/status.wsgi

After the Apache HTTP Server is restarted test the mod_wsgi by taking a look at the Python Status.

trick7.1.11. Module mod_perl configuration

Mod_perl brings together the full power of the Perl programming language and the Apache HTTP server. You can use Perl to manage Apache, respond to requests for web pages and much more. Mod_perl is more than CGI scripting on steroids. It is a whole new way to create dynamic content by utilizing the full power of the Apache web server to create stateful sessions, customized user authentication systems, smart proxies and much more. Yet, magically, your old CGI scripts will continue to work and work very fast indeed. With mod_perl you give up nothing and gain so much!

When ppm install mod_perl is run it will also fetch the Apache2 module mod_perl.so. When asked Where should mod_perl.so be placed? just answer P:\dev\apps\httpserver\apache-2.2.21\modules [version 2.000004].

Note

In case of an upgrade just ppm uninstall mod_perl first.

Include 1 this Perl module just before httpd-vhosts.conf in P:\dev\apps\httpserver\apache-conf\httpd.conf:

# Perl
Include ../apache-conf/httpd-perl.conftrick1

# Virtual hosts
Include ../apache-conf/httpd-vhosts.conf

with the following content in P:\dev\apps\httpserver\apache-conf\httpd-perl.conf:

# Perl
LoadModule perl_module modules/mod_perl.so

<IfModule mod_perl.c>
    <Location /perl-status>
        SetHandler perl-script
        PerlHandler Apache2::Status
        PerlSetVar StatusOptionsAll On
   
        Order deny,allow
        Deny from all
        Allow from 127.0.0.1
    </Location>
</IfModule>

# Perl Sample
Include ../apache-conf/httpd-perl-sample.conf

It is possible to verify the installation using the instructions of the mod_perl Manual. Or just create the following file P:\dev\apps\httpserver\sample\perl\test.pm:

package sample::perl::test;
use strict;

use Apache2::RequestRec ();  # for $r->content_type
use Apache2::RequestIO ();   # for $r->puts
use Apache2::Const -compile => ':common';

sub handler {
    my $r = shift;
    my $time = scalar localtime();
    my $package = __PACKAGE__;
    $r->content_type('text/html');
    $r->puts(<<"END");

<HTML><BODY>
<h3>Test</H3>
Hello from <B>$package</B>! The time is $time.
</BODY></HTML>
END

    return Apache2::Const::OK;
}

1;

Register this perl handler in P:\dev\apps\httpserver\apache-conf\httpd-perl-sample.conf:

<IfModule mod_perl.c>
    PerlSwitches -IP:/dev/apps/httpserver/
    PerlModule sample::perl::test

    <Location /manual/perl>
       SetHandler modperl
       PerlResponseHandler sample::perl::test
    </Location>
</IfModule>

After the Apache HTTP Server is restarted test the mod_perl module at http://dev.net/manual/perl and take a look at the Perl Status. In case of memory problems read up on Apache2::SizeLimit - Because size does matter (see also Bugzilla mod_perl.pl).

trick7.1.12. Module mod_dav configuration

Mod_dav provides class 1 and class 2 WebDAV (Web-based Distributed Authoring and Versioning) functionality for Apache. This extension to the HTTP protocol allows creating, moving, copying, and deleting resources and collections on a remote web server.

Enable the following modules 1-3 in P:\dev\apps\httpserver\apache-2.2.21\conf\httpd.conf:

LoadModule cgi_module modules/mod_cgi.so
#LoadModule charset_lite_module modules/mod_charset_lite.so
trick1LoadModule dav_module modules/mod_dav.so
trick2LoadModule dav_fs_module modules/mod_dav_fs.so
trick3LoadModule dav_lock_module modules/mod_dav_lock.so

For example include 1 the Maven Sites WebDAV configuration just before httpd-vhosts.conf in P:\dev\apps\httpserver\apache-conf\httpd.conf:

# Maven Sites
Include ../apache-conf/httpd-mvn.conftrick1

# Virtual hosts
Include conf/extra/httpd-vhosts.conf

with the following content in P:\dev\apps\httpserver\apache-conf\httpd-mvn.conf:

<IfModule dav_module>
<IfModule dav_fs_module>
<IfModule dav_lock_module>
    DavLockDB "P:/dev/data/httpserver/webdav/DavLock"

    Alias /mvn-sites "P:/dev/data/httpserver/mvn/sites"
    
    <Directory "P:/dev/data/httpserver/mvn/sites">
        Dav On
        DavMinTimeout 120

        Options Indexes
          
        Include ../apache-conf/httpd-realm.conf  
    </Directory>
</IfModule>
</IfModule>
</IfModule>

Don't forget to create the specified directories: P:\dev\data\httpserver\webdav and P:\dev\data\httpserver\mvn\sites.

trick7.1.13. Server info

The mod_info module provides a comprehensive overview of the server configuration including all installed modules and directives in the configuration files. And the mod_status module allows a server administrator to find out how well their server is performing.

In the P:\dev\apps\httpserver\apache-2.2.21\conf\httpd.conf file uncomment those two modules 1-2 and the corresponding config include 3:

LoadModule include_module modules/mod_include.so
trick1LoadModule info_module modules/mod_info.so
...
#LoadModule ssl_module modules/mod_ssl.so
trick2LoadModule status_module modules/mod_status.so

...

# Real-time info on requests and configuration
trick3Include conf/extra/httpd-info.conf

In the P:\dev\apps\httpserver\apache-2.2.21\conf\extra\httpd-info.conf file restrict access 1 to localhost:

#
# Allow server status reports generated by mod_status,
# with the URL of http://servername/server-status
# Change the ".dev.net" to match your domain to enable.

<Location /server-status>
    SetHandler server-status
    Order deny,allow
    Deny from all
    Allow from .dev.net 127.0.0.1trick1
</Location>

#
# ExtendedStatus controls whether Apache will generate "full" status
# information (ExtendedStatus On) or just basic information (ExtendedStatus
# Off) when the "server-status" handler is called. The default is Off.
#
#ExtendedStatus Ontrick2

#
# Allow remote server configuration reports, with the URL of
#  http://servername/server-info (requires that mod_info.c be loaded).
# Change the ".dev.net" to match your domain to enable.
#
<Location /server-info>
    SetHandler server-info
    Order deny,allow
    Deny from all
    Allow from .dev.net 127.0.0.1trick1
</Location>

Note

Keep the full status settings 2 disabled, performance wise. After the Apache HTTP Server is restarted take a look at the Apache Server Status and the Apache Server Information.

trickChapter 8. Web Server

trick8.1. Tomcat

Apache Tomcat is an implementation of the Java Servlet and JavaServer Pages technologies.

trick8.1.1. Resources

trick8.1.2. Tomcat installation guide

Download the archive: apache-tomcat-7.0.25-windows-x86.zip [version 7.0.25].

Extract this .zip file to P:\dev\apps\webserver.

trick8.1.2.1. HTTP Binding

Configure Tomcat settings 1-7 in the file P:\dev\apps\webserver\apache-tomcat-7.0.25\conf\server.xml:

<Server port="80058070trick1" address="127.0.0.1"trick2 shutdown="SHUTDOWN">
    ...
    <Connector port="80808068trick3" address="127.0.0.1"trick4 protocol="HTTP/1.1" 
               connectionTimeout="20000" 
               redirectPort="8443"trick5 URIEncoding="UTF-8"trick6/>
    ...
    <Connector port="80098069trick7" address="127.0.0.1"trick8 protocol="AJP/1.3" 
               redirectPort="8443"trick5 URIEncoding="UTF-8"trick6/>

trick8.1.2.2. Tomcat access

Configure Tomcat access in the file P:\dev\apps\webserver\apache-tomcat-7.0.25\conf\tomcat-users.xml as follows:

<?xml version='1.0' encoding='utf-8'?>
<tomcat-users>
  <!-- Tomcat Web Application Manager -->
  <role rolename="manager-gui"/>
  <role rolename="manager-script"/>
  <role rolename="manager-jmx"/>
  <role rolename="manager-status"/>
  
  <!-- Tomcat Virtual Host Manager -->
  <role rolename="admin-gui"/>
  <role rolename="admin-script"/>
  
  <user username="admin" password="password-gui" roles="manager-gui,admin-gui"/>
  <user username="script-tool" password="password-tool" roles="manager-script,admin-script"/>
  <user username="jmx-tool" password="password-tool" roles="manager-jmx"/>
  <user username="status" password="password-status-only" roles="manager-status"/>
</tomcat-users>

These roles are used by the following two applications respectively:

  1. Tomcat Web Application Manager:

    Status interface for all four users at http://localhost:8068/manager/status

  2. Tomcat Virtual Host Manager:

trick8.1.3. Windows service

To restart automatically on Microsoft Windows create a service as follows:

cd /d P:\dev\apps\webserver\apache-tomcat-7.0.25

set CATALINA_HOME=P:\dev\apps\webserver\apache-tomcat-7.0.25
bin\service.bat install tomcat

bin\tomcat7.exe //US//tomcat --DisplayName="dev.net Tomcat" ^
  --Description="Tomcat is an open source web server." ^
  --Startup=auto

bin\tomcat7.exe //US//tomcat --JvmMx=512 --JvmMs=128 ^
  ++JvmOptions=-XX:MaxPermSize=192m

Note

In case of an upgrade sc delete tomcat first.

Important

In case of a new jdk installation just run bin\tomcat7.exe //US//tomcat --Jvm auto.

Start it with net start tomcat.

Verify the installation and the JVM memory usage at http://localhost:8068/manager/status.

trick8.1.3.1. Tomcat Windows user

For easier management of user specific files such as for example the Maven C:\Users\tomcat\.m2\settings-security.xml select Start MenuControl PanelUser Accounts and Family SafetyUser AccountsAdd or remove user accountsCreate a new account Tomcat as Standard user and click Create Account. Select this new user and Create a password.

Launch the Service Management Console with services.msc. Right click on dev.net Tomcat and select PropertiesLog On to use This account .\tomcat. After password conformation click Ok and restart the service.

trick8.1.3.1.1. netrc

The _netrc file contains login and initialization information used by the auto-login process.

When logged in as tomcat user type the following commands:

setx HOME %USERPROFILE%
echo machine dev.net login jenkins password <password> >> %USERPROFILE%\_netrc

This way the Jenkins build jobs will be able to auto-login to the git-repo on dev.net.

Restart tomcat service to pick up HOME setting.

trick8.1.3.2. Tomcat Manager

Tomcat7w is a GUI application for monitoring and configuring Tomcat services.

To monitor the tomcat service run: P:\dev\apps\webserver\apache-tomcat-7.0.25\bin\tomcat7w.exe //MS//tomcat or create a shortcut Tomcat Manager for it in StartProgramsStartup and edit PropertiesTarget to include the correct service name P:\dev\apps\webserver\apache-tomcat-7.0.25\bin\tomcat7w.exe //MS//tomcat.

When the Tomcat Manager is running, you can see the dev.net Tomcat icon in the system tray. Right click on this icon and select Configure to activate the console in which the Apache Tomcat Server can be (re)started and stopped.

Note

When the monitor application is already running when the Log On account is changed (as described in the prior Section 8.1.3.1, “Tomcat Windows user”) right click on its icon and select Exit and then restart it. Because this change wont show up otherwise.

trick8.1.4. Logging

Tomcat 7.0 uses Commons Logging throughout its internal code allowing the developer to choose a logging configuration that suits their needs such as Log4J.

To switch to Log4J apply the following steps:

  1. Tomcat replacements:

    • Download: tomcat-juli-adapters.jar and tomcat-juli.jar.

    • Replace the tomcat-juli.jar in P:\dev\apps\webserver\apache-tomcat-7.0.25\bin.

    • Install the tomcat-juli-adapters.jar in the P:\dev\apps\webserver\apache-tomcat-7.0.25\lib directory.

  2. Log4J integration:

    • Download: apache-log4j-1.2.16.zip [version 1.2.16].

    • Install the log4j-1.2.16.jar in the P:\dev\apps\webserver\apache-tomcat-7.0.25\lib directory.

  3. SLF4J integration:

    • Download: slf4j-1.6.4.zip used by frameworks such as Hibernate [version 1.6.4].

    • Install the slf4j-api-1.6.4.jar in the P:\dev\apps\webserver\apache-tomcat-7.0.25\lib directory.

    • And bind SLF4J to Log4J by installing the slf4j-log4j12-1.6.4.jar in the P:\dev\apps\webserver\apache-tomcat-7.0.25\lib directory.

  4. Logging configuration:

    • Create a file called log4j.xml in P:\dev\logs\webserver\tomcat with the following content:

      <?xml version="1.0" encoding="UTF-8"?>
      <!DOCTYPE log4j:configuration 
                SYSTEM "http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/xml/doc-files/log4j.dtd">
      
      <log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/" debug="true">
        <appender name="FILE" class="org.apache.log4j.RollingFileAppender">
          <param name="File" value="P:/dev/logs/webserver/tomcat/tomcat.log4j"/>
          <param name="Append" value="true"/>
          <param name="MaxFileSize" value="100MB"/>
          <param name="MaxBackupIndex" value="5"/>
          <layout class="org.apache.log4j.PatternLayout">
            <param name="ConversionPattern" value="%d %-5p [%t] %c{2} %x - %m%n"/>
          </layout>
        </appender>
      
        <logger name="org.apache.catalina">
          <level value="INFO"/>
        </logger>
      
        <root>
          <level value="INFO"/>
          <appender-ref ref="FILE"/>
        </root>
      </log4j:configuration>
      
    • Delete the obsolete P:\dev\apps\webserver\apache-tomcat-7.0.25\conf\logging.properties or rename to logging.properties.obsolete.

    • Configure the tomcat service to use the log4j.xml instead as follows:

      cd /d P:\dev\apps\webserver\apache-tomcat-7.0.25
      
      bin\tomcat7.exe //US//tomcat ^
        ++JvmOptions=-Dlog4j.configuration=file:///P:/dev/logs/webserver/tomcat/log4j.xml
      
      bin\tomcat7.exe //US//tomcat ^
        --LogPath=P:/dev/logs/webserver/tomcat
      

trick8.1.5. Apache configuration

Instruct Apache to proxy all URLs whose path portions begin with /tomcat/ using the following P:\dev\apps\httpserver\apache-conf\httpd-vhosts.conf include 1:

<VirtualHost *:80>
    ...

    <IfModule proxy_module>
    <IfModule proxy_http_module>
        ...

        <Proxy *>
            ...
        </Proxy>

        # Tomcat
        Include ../apache-conf/httpd-tomcat.conftrick1
    </IfModule>
    </IfModule>
</VirtualHost>

with the following content in P:\dev\apps\httpserver\apache-conf\httpd-tomcat.conf (see also Section 7.1.9.2, “Html rewrite configuration”):

<IfModule headers_module>
<IfModule proxy_html_module>
<IfModule proxy_module>
<IfModule proxy_http_module>
    Redirect /tomcat   /tomcat/
    ProxyPass /tomcat/ http://localhost:8068/

    <Location /tomcat/>
        ProxyPassReverse /
        ProxyHTMLEnable On
        RequestHeader unset Accept-Encoding
        ProxyHTMLURLMap http://localhost:8068 /tomcat
        ProxyHTMLURLMap /                     /tomcat/
        ProxyHTMLURLMap /tomcat/              /tomcat/
    </Location>
</IfModule>
</IfModule>
</IfModule>
</IfModule>

trick8.1.5.1. Remote authentication

For the AJP protocol connector tell Tomcat not to use its internal (primitive) authentication mechanism, but instead to use remote authentication provided by the front-end web server with the following setting 1 in the file P:\dev\apps\webserver\apache-tomcat-7.0.25\conf\server.xml:

    <Connector address="127.0.0.1" port="8069" protocol="AJP/1.3" 
               tomcatAuthentication="false"trick1
               URIEncoding="UTF-8"/>

When the Tomcat web server and the Apache HTTP Server are restarted you should be able to browse Tomcat at http://dev.net/tomcat/.

trickChapter 9. Application Server

trick9.1. GlassFish

GlassFish, built by the GlassFish community, is the first compatible implementation of the Java EE 6 platform specification and is built on a modular, flexible runtime based on the OSGi standard.

trick9.1.1. Resources

trick9.1.2. GlassFish installation guide

Download the Windows Platform installer bundle: glassfish-3.1.1-windows.exe [version 3.1.1].

Run this .exe file to install GlassFish:

  • Installation Type: Custom Installation.

  • Installation: Install and Configure.

  • Installation Directory: P:\dev\apps\appserver\glassfish.

  • Select a Java SDK from the list: P:\dev\apps\prg\java\jdk1.7.0_09.

  • Check Install Update Tool and Enable Update Tool.

  • Ready to Install: and click Install

  • Configuration: Create a server domain.

  • Domain Info:

    • Domain Name: glassfish-domain.

    • Admin Port: 4848.

    • Http Port: 8071.

    • Username: admin.

    • Password: password.

    • Check Create Operating System service for the domain.

    • Service Name: glassfish.

    • Check Start domain after creation.

  • After installation summary click Exit.

trickChange the listener addresses to localhost 1 (to restrict access), host IP 3 (to allow local area network access; see also 192.168.0.xx host) and optionally disable the ssl 2 connections by editing the configuration file P:\dev\apps\appserver\glassfish\glassfish\domains\glassfish-domain\config\domain.xml:

<domain
  ...
 <configs>
   <config name="server-config">
      ...
      <iiop-service>
        ...
        <iiop-listener address="0.0.0.0127.0.0.1trick1" port="3700" ...
        <iiop-listener ... address="0.0.0.0127.0.0.1trick1" port="3820" 
              enabled="false"trick2 id="SSL">
          ...
        </iiop-listener>
        <iiop-listener ... address="0.0.0.0127.0.0.1trick1" port="3920" 
              enabled="false"trick2 id="SSL_MUTUALAUTH">
          ...
        </iiop-listener>
      </iiop-service>
      <admin-service ... system-jmx-connector-name="system">
        <jmx-connector ... address="0.0.0.0192.168.0.xxtrick3" port="8686" 
             name="system" />
        ...
      </admin-service>
      ...
      <network-config>
          ...
          <network-listeners>
          <network-listener port="8071" address="127.0.0.1"trick1 ...
          <network-listener port="8181" address="127.0.0.1"trick1 
                   enabled="false"trick2 ...  
          <network-listener port="4848" address="192.168.0.xx"trick3 ... 
        </network-listeners>
        ...
      </network-config>
      ...
    </config> 
  </configs>
  <property name="administrative.domain.name" value="glassfish-domain"/>
</domain>

Press Windows Logo+Break keys to open the Windows System Properties. Select Advanced system settingsEnvironment Variables and Edit the Path to append %GLASSFISH_HOME%\bin;. Also add a New system variable GLASSFISH_HOME pointing to P:\dev\apps\appserver\glassfish.

For administration tasks, the GlassFish server software provides the following tools, which enable administrators to manage server instances:

  • The Admin Console, a browser-based graphical user interface (GUI).

  • The asadmin utility, a command-line tool.

Stop the server by entering the command asadmin stop-domain glassfish-domain.

Now start the service by entering the command net start glassfish.

Verify that the server is running in your browser at http://localhost:8071.

trick9.1.3. Upgrade tool

The GlassFish Server Upgrade Tool is tended solely for performing side-by-side upgrades from any compatible older product version to GlassFish Server 3.1. A side-by-side upgrade means that the new GlassFish Server release is installed in a different directory than the release from which it is being upgraded. Alternatively use the Update Tool.

trick9.1.4. Update tool

Unlike the Upgrade Tool, when you use the Update Tool or the pkg utility to perform a GlassFish Server in-place upgrade, the source server and the target server are installed on the same machine and in the same installation directories. For more information see also this pdf.

From the command line run: P:\dev\apps\appserver\glassfish\updatetool\bin\updatetool.exe and optionally select EditPreferences...Updates and check Automatically check for updates as required Weekly or so and click Ok.

trick9.1.5. Changing JDK version

Updating GlassFish to run with a JDK version that is different to the one used during installation will affect all local domains. To do this, update the following in the file P:\dev\apps\appserver\glassfish\glassfish\config\asenv.bat:

REM  Yet, this file is also where users of earlier versions have sometimes added
REM  a definition of AS_JAVA to control which version of Java GlassFish
REM  should use.  As a result, in order to run a user-specified version of Java,
REM  the asadmin and appclient scripts do indeed invoke this file as a
REM  script - but ONLY to define AS_JAVA.  Any calling script should not
REM  rely on the other settings because the relative paths will be resolved
REM  against the current directory when the calling script is run, not the
REM  installation directory of GlassFish, and such resolution will not work
REM  correctly unless the script happens to be run from the GlassFish
REM  installation directory.
...
set AS_JAVA=C:\dev\Java\jdk1.7.0_09

trick9.1.6. Autodeploy

Just copy the application, which is packaged as Java ARchive (JAR), Web ARchive (WAR), or Enterprise ARchive (EAR) file, into P:\dev\apps\appserver\glassfish\glassfish\domains\glassfish-domain\autodeploy\.

A pre-packaged application that says Hello can be downloaded from http://glassfish.dev.java.net/downloads/quickstart/hello.war.

trick9.1.7. Admin console

Access http://dev.net:4848. Enter the admin user name and password.

In the left pane, click the Applications node. If you already have the hello.war application deployed, undeploy it by selecting the checkbox next to it and clicking Undeploy. To deploy a newly assembled application click Deploy....

To verify that it was deployed properly, click Launch.

trick9.1.8. JVM switches for performance

JVMs offer a variety of standard and non-standard switches that tune memory allocation and garbage collection behavior. Some of these settings can benefit glassfish-domain performance:

  • -Xms256m - this setting tells the Java virtual machine to set its initial heap size to 256 megabytes. By telling the JVM how much memory it should initially allocate for the heap, we save it growing the heap as applications consume more memory. This switch improves startup time.

  • -Xmx512m (default GlassFish setting) - this settings tells the Java virtual machine the maximum amount of memory it should use for the heap. Placing a hard upper limit on this number means that the Java process cannot consume more memory than physical RAM available. This limit can be raised on systems with more memory. Current default value is 512MB.

    Warning

    Do not set this value to near or greater than the amount of physical RAM in your system or it will cause severe swapping during runtime.

  • -Xverify:none - this switch turns off Java bytecode verification, making classloading faster, and eliminating the need for classes to be loaded during startup solely for the purposes of verification. This switch improves startup time, and there is no reason not to use it.

  • -XX:+UseAdaptiveSizePolicy - this switch may help improve garbage collector throughput and memory footprint. It is part of garbage collector ergonomics implemented in JDK5.0.

  • -XX:+UseParallelGC - some tests have shown that, at least on systems fairly well equipped with memory, the durations of minor garbage collections is halved when using this collection algorithm, on uniprocessor systems. Note that this is paradoxical - this collector is designed to work best on multiprocessor systems with gigabyte heaps. No data is available on its effect on major garbage collections. This collector is mutually exclusive with -XX:+UseConcMarkSweepGC.

  • Optional -XX:CompileThreshold=100 - this switch will make startup time slower, by HotSpot to compile many more methods down to native code sooner than it otherwise would. The reported result is snappier performance once the server is running, since more of the code will be compiled rather than interpreted. This value represents the number of times a method must be called before it will be compiled.

  • Optional -XX:MaxPermSize=192m (since GlassFish version 2 beta 2 the option is activated with default setting of 192m) - In some cases, such as when applications that request quite a lot of memory, the server can run out of a different type of memory (Permanent Generation), and if this is the case the above settings may not help solve the memory issue. A problem like this may occur when running multiple applications on the same server.

You could connect to the GlassFish Admin GUI and select: Configurationsserver-configJVM SettingsJVM Options and click Add JVM Option repeatedly. After entering the last option don't forget to click Save and restarting the service (see the message in the banner Restart Required).

Or stop the domain and just edit P:\dev\apps\appserver\glassfish\glassfish\domains\glassfish-domain\config\domain.xml to try out the jvm options 1-7 (some might already configured):

  <configs>
    <config name="server-config">
      ...
      <java-config ...>
        <jvm-options>-XX:MaxPermSize=192m</jvm-options>trick1
        <jvm-options>-Xrs</jvm-options>
        <jvm-options>-client</jvm-options>
        ...
        <jvm-options>-Xms256m</jvm-options>trick2
        <jvm-options>-Xmx512m</jvm-options>trick3
        <jvm-options>-Xverify:none</jvm-options>trick4
        ...
        <jvm-options>-XX:NewRatio=2</jvm-options>
        <jvm-options>-XX:+UseParallelGC</jvm-options>trick5
        <jvm-options>-XX:+UseAdaptiveSizePolicy</jvm-options>trick6
        <jvm-options>-XX:CompileThreshold=100</jvm-options>trick7
      </java-config>

Restart the domain.

trick9.1.9. Apache configuration

Instruct Apache to proxy all URLs whose path portions begin with /glassfish/ and /console/ using the following P:\dev\apps\httpserver\apache-conf\httpd-vhosts.conf include 1:

<VirtualHost *:80>
    ...

    <IfModule proxy_module>
    <IfModule proxy_http_module>
        ...

        <Proxy *>
            ...
        </Proxy>

        # GlassFish
        Include ../apache-conf/httpd-glassfish.conftrick1
    </IfModule>
    </IfModule>
</VirtualHost>

with the following content in P:\dev\apps\httpserver\apache-conf\httpd-glassfish.conf:

<IfModule headers_module>
<IfModule proxy_html_module>
<IfModule proxy_module>
<IfModule proxy_http_module>
    Redirect /glassfish   /glassfish/
    ProxyPass /glassfish/ http://localhost:8071/

    <Location /glassfish/>
        ProxyPassReverse /
        ProxyHTMLEnable On
        RequestHeader unset Accept-Encoding
        ProxyHTMLURLMap http://localhost:8071 /glassfish
        ProxyHTMLURLMap /                     /glassfish/
        ProxyHTMLURLMap /glassfish/           /glassfish/

        Include ../apache-conf/httpd-realm.conf
    </Location>
</IfModule>
</IfModule>
</IfModule>
</IfModule>

When the domain and the Apache HTTP Server are restarted you should be able to browse GlassFish at http://dev.net/glassfish.

trickChapter 10. Database

trick10.1. MySQL

MySQL is the world's most popular open source database.

trick10.1.1. Resources

trick10.1.2. MySQL installation guide

Download the Win32 binary (MSI Installer): mysql-5.5.25-win32.msi [version 5.5.25].

Run this .msi file. The installation will ask you for the following information:

  • A setup type: Custom to click Next.

  • For MySQL Server and thus Client Programs click Browse... the install path to: P:\dev\apps\db\mysql-5.5.

  • For Server data files click Browse... the install path to: P:\dev\data\db\mysql and click Next to Install.

  • Keep the checkbox Configure the MySQL Server now checked and Finish the installation.

The the MySQL Server Instance Configuration Wizard handles the following settings (in case of an upgrade select Cancel):

  • Configuration type: Detailed Configuration.

  • Server type: Developer Machine.

  • Database usage: Multifunctional Database.

  • The drive for the InnoDB datafile: P: and change Intallation Path to \dev\data\db\mysql\innodb.

  • The approximate number of concurrent connections to the server: Decision Support (DSS)/OLAP

  • Network options: Enable TCP/IP Networking on Port Number: 3306.

  • The server SQL mode: Enable Strict Mode

  • The default character set: Best Support for Multilingualism

  • Windows options: Install As Windows Service (only because otherwise the Security Options won't show) with Service Name: MySQL and Launch the MySQL Server automatically.

  • Security options: Modify Security Settings set root password. Disable root access from remote machines and do not Create An Anonymous Account.

Above entered settings can be found in P:\dev\apps\db\mysql-5.5\my.ini.

trickPress Windows Logo+Break keys to open the Windows System Properties. Select Advanced system settingsEnvironment Variables and Edit the Path to append %MYSQL_HOME%\bin;. Also add a New system variable MYSQL_HOME pointing to P:\dev\apps\db\mysql-5.5.

Verify the installation with mysqlshow mysql -u root -p and/or mysqladmin version status proc -u root -p. To see a list of options provided by mysql, invoke it with the --help option.

trick10.1.3. Backup options

  1. The mysqldump client is a backup program. It can be used to dump a database or a collection of databases for backup or transfer to another SQL server (not necessarily a MySQL server).

    Create a batch file P:\dev\apps\windows\batch\mysql-backup-all.bat:

    @echo off
    
    if not "%1"=="" goto backupDatabases
    
    echo Usage: mysql-backup-all ^<isodate^>
    goto end
    
    :backupDatabases
    if not exist B:\dev\backup\db\mysqldump mkdir B:\dev\backup\db\mysqldump
    cd /d B:\dev\backup\db\mysqldump
    mysqldump --single-transaction --routines --triggers -q --all-databases ^
              -u root -p > B:\dev\backup\db\mysqldump\all.%1.sql
    
    :end
    

    To dump all databases use the following statement: mysql-backup-all 20091205.

    Create a batch file P:\dev\apps\windows\batch\mysql-backup-db.bat:

    @echo off
    
    if not "%2"=="" goto backupDatabase
    
    echo Usage: mysql-backup-db ^<databasename^> ^<isodate^>
    goto end
    
    :backupDatabase
    if not exist B:\dev\backup\db\mysqldump mkdir B:\dev\backup\db\mysqldump
    cd /d B:\dev\backup\db\mysqldump
    mysqldump --single-transaction --routines --triggers -q %1 ^
              -u root -p > B:\dev\backup\db\mysqldump\%1.%2.sql
    
    :end
    

    To dump a specific database (for example mysql) use the following statement: mysql-backup-db mysql 20091205.

  2. You can also create a binary backup by simply archiving the complete P:\dev\data\db\mysql directory, when the MySQL service is shut down.

    Tip

    To reduce downtime backup a slave that is replicating data from a master. Because the slave can be paused and shut down without affecting the running operation of the master you can produce an effective snapshot of 'live' data that would otherwise require a shutdown of the master database.

trick10.1.4. Replication

MySQL replication is based on the master server keeping track of all changes to your databases (updates, deletes, and so on) in its binary logs.

trick10.1.4.1. Slave user

Create the replication user as follows:

mysql -u root -p
mysql> grant replication slave on *.* to 'slave-user'@'localhost' 
    ->  identified by 'password';
mysql> flush privileges;
mysql> select host,user from mysql.user;
mysql> quit

trick10.1.4.2. Master and slave configuration

Copy P:\dev\apps\db\mysql-5.5\my.ini to P:\dev\apps\db\mysql-conf\mysql-master.ini and P:\dev\apps\db\mysql-conf\mysql-slave.ini.

Configure the master in P:\dev\apps\db\mysql-conf\mysql-master.ini with the following settings 1-9:

[mysqld]
server-id=1trick1
report-host=dev.nettrick2
report-port=3306trick3
log-bin="P:/dev/logs/db/mysql/mysql-master-bin"trick4
expire_logs_days=30trick5
binlog_format=MIXEDtrick6
log-error="P:/dev/logs/db/mysql/mysql-master-error.log"trick7
max_allowed_packet=32Mtrick8

# The TCP/IP Port the MySQL Server will listen on
port=3306

...

innodb_flush_log_at_trx_commit=1
sync_binlog=1trick9

Important

When upgrading make sure that innodb_log_file_size uses the old value otherwise MySQL won't start.

Configure the slave in P:\dev\apps\db\mysql-conf\mysql-slave.ini with the following settings 2-9:

[client]
port=3307trick1

...

[mysqld]
server-id=11trick2
report-host=dev.nettrick3
report-port=3307trick4
log-error="Strick5:/dev/logs/db/mysql/mysql-slave-error.log"
relay-log="Strick6:/dev/logs/db/mysql/mysql-slave-relay-bin"
max_allowed_packet=32Mtrick7

# The TCP/IP Port the MySQL Server will listen on
port=3307trick1

#Path to installation directory. All paths are usually resolved relative to this.
basedir="P:/dev/apps/db/mysql-5.5/"

#Path to the database root
datadir="Strick8:/dev/data/db/mysql/Data/"

...

#*** INNODB Specific options ***
innodb_data_home_dir="Strick9:/dev/data/db/mysql/innodb/"

Create the logging directories with mkdir P:\dev\logs\db\mysql and mkdir S:\dev\logs\db\mysql.

Note

It could be interesting to see if there are performance changes when datadir and log-bin are residing on separate drives themselves? And what if the database is hosted on another drive than the application servers? Creating symbolic links for P:\dev\data\db\mysql and P:\dev\logs\db\mysql using Junction could do the trick to check some results without the need to change drive letters in the this chapter configured .bat, mysql*.ini and mysql-master-bin.index content. By the way the MySQL master database seemed to respond 3-4 times faster when replication (comment out log-bin, expire_logs_days and binlog_format) was turned off.

trick10.1.4.3. Fine-Tuning full-text search

MySQL's full-text search capability has few user-tunable parameters. To allow small words (required by Bugzilla) edit both mysql-master.ini and mysql-slave.ini to add the following settings in [myslqd] 1 and the new [myisamchk] 2 at the end of the file:

[mysqld]
...

# Set the SQL mode to strict
sql-mode="STRICT_TRANS_TABLES,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION"

# Allow small words in full-text indexes
ft_min_word_len=2trick1

...

[myisamchk]
ft_min_word_len=2trick2

trick10.1.4.4. Windows service

Stop the MySQL server with mysqladmin shutdown -h 127.0.0.1 -P 3306 -u root -p or net stop MySQL or sc stop MySQL and use sc query MySQL to verify the server is stopped. Delete the old MySQL service with sc delete MySQL.

Make a data snapshot for the slave by copying the raw data files from the master with xcopy /E /I P:\dev\data\db\mysql S:\dev\data\db\mysql.

With the following batch file P:\dev\apps\windows\batch\mysql-create-service.bat:

@echo off

if not "%1"=="" goto createService

echo Usage: mysql-create-service ^<master^|slave^>
goto end

:createService
setlocal

set SERVICE_ID=mysql%1
set SERVICE_DISPLAY_NAME="dev.net MySQL %1"
set SERVICE_EXE=%MYSQL_HOME%\bin\mysqld.exe
set SERVICE_START_CMD=--defaults-file=\"P:\dev\apps\db\mysql-conf\mysql-%1.ini\"
set SERVICE_STOP_CMD=

sc create %SERVICE_ID% ^
   binPath= "%SERVICE_EXE% %SERVICE_START_CMD% %SERVICE_ID% %SERVICE_STOP_CMD%" ^
   start= auto ^
   DisplayName= %SERVICE_DISPLAY_NAME%

sc description %SERVICE_ID% "MySQL is a SQL database management system."

endlocal

:end

Define the services for the master and slave: mysql-create-service master and mysql-create-service slave. Start both servers with sc start mysqlmaster and sc start mysqlslave.

trick10.1.4.5. Slave activation

Connect to the master with mysql [-P 3306] -u root -p and show master status\G.

Use this file and position information for configuration of the slave with mysql -P 3307 -u root -p to change master to master_host='localhost', master_user='slave-user', master_password='password', master_log_file='mysql-master-bin.00000x', master_log_pos=y;.

Now start slave; and verify with show slave status\G.

trick10.1.5. Upgrading

Backup the mysql database separately, for example:

mysql-backup-db mysql 20120611
mysql-backup-db fisheye 20120611
mysql-backup-db jira 20120611
mysql-backup-db sonar 20120611
mysql-backup-db test 20120611

Stop the master and slave services:

net stop mysqlslave
net stop mysqlmaster

Backup the MySQL configuration:

xcopy /E /I P:\dev\apps\db\mysql-conf B:\dev\backup\db\mysql-conf-20120611

Backup the data directory also:

xcopy /E /I P:\dev\data\db\mysql B:\dev\backup\db\mysql-20120611

Remove master and slave services:

sc delete mysqlslave
sc delete mysqlmaster

After the backup optionally remove slave data and logs for a fresh start:

rmdir P:\dev\logs\db\mysql [/q] /s

rmdir S:\dev\data\db\mysql [/q] /s
rmdir S:\dev\logs\db\mysql [/q] /s

mkdir P:\dev\logs\db\mysql

Download the Win32 binary (MSI Installer): mysql-5.5.25-win32.msi [version 5.5.25].

Run this .msi file and select Upgrade. At the end skip the the MySQL Server Instance Configuration Wizard.

In case of a minor version change, from say 5.1 to 5.5, also Edit system variable MYSQL_HOME pointing to P:\dev\apps\db\mysql-5.5. Likewise edit P:\dev\apps\db\mysql-conf\mysql-master.ini and P:\dev\apps\db\mysql-conf\mysql-slave.ini settings basedir 1 and deprecated default-character-set 2 under [mysqld]:

#Path to installation directory. All paths are usually resolved relative to this.
basedir="P:/dev/apps/db/mysql-5.5/"trick1

#Path to the database root
datadir="P:/dev/data/db/mysql/Data/"

# The default character set that will be used when a new schema or table is
# created and no character set is defined
default-character-setcharacter-set-server=utf8trick2

Redefine the Windows services for the master and slave: mysql-create-service master and mysql-create-service slave.

Restart the master with net start mysqlmaster.

Mysql_upgrade examines all tables in all databases for incompatibilities with the current version of MySQL Server. Mysql_upgrade also upgrades the system tables so that you can take advantage of new privileges or capabilities that might have been added.

Upgrade the master with mysql_upgrade -P 3306 -u root -p. After successfully running this command the file P:\dev\data\db\mysql\data\mysql_upgrade_info should contain: 5.5.25.

Optionally use this upgraded version as the above mentioned fresh start for the slave:

net stop mysqlmaster

xcopy /E /I P:\dev\data\db\mysql S:\dev\data\db\mysql
mkdir S:\dev\logs\db\mysql

Restart both master and slave.

Note

Because the slave database is based on the backup of the master it needs to be reactivated (see Section 10.1.4.5, “Slave activation”).

trick10.1.6. Maatkit

Maatkit (formerly MySQL Toolkit) contains essential command-line tools for MySQL, such as table checksums, a query profiler, and a visual EXPLAIN tool. It provides missing features such as checking whether slaves have the same data as the master.

Download the archive: maatkit-7540.zip [version 7540].

Extract this .zip file to P:\dev\apps\db.

Install Maatkit in Perl directory using C++ make as follows:

cd /d P:\dev\apps\db\maatkit-7540
perl Makefile.PL
make install

Important

Don't install MinGW and dependency dmake because we will be using Microsoft C++. And the combination will result in the following error when running make install: NMAKE : fatal error U1077: 'P:\dev\apps\prg\perl-5.12.4.1205\bin\perl.exe' : return code '0xff'.

Verify the installation with mk-table-checksum localhost,P=3306 -u root --ask-pass.

trick10.1.6.1. A very fast hash function

A User-Defined Function that implements the FNV (Fowler-Voll-No) hash function for MySQL.

To install this functionality first create a DLL for it.

Download the archive: mysql-5.5.25-win32.zip [version 5.5.25].

Extract from this .zip file only the mysql-5.5.25-win32\include directory to P:\dev\apps\db\maatkit-7540\udf.

Start Visual C++ and select FileNewProject From Existing Code... and click Next to configure the following settings:

  • Project file location: P:\dev\apps\db\maatkit-7540\udf.

  • Project name: fnv_udf and click Next.

  • Project type: Dynamically linked library (DLL) project and click Next.

  • Include search paths (/I): P:\dev\apps\db\maatkit-7540\udf\mysql-5.5.25-win32\include and click Finish.

Right click on Solution 'fnv_udf' and select Configuration Manager... to set Active solution configuration: Release and click Close.

Edit the fnv_udf.cc file to add the fnv_64 function definition for the DLL with the following settings 1-3:

 * By:
 *  chongo <Landon Curt Noll> /\oo/\
 *      http://www.isthe.com/chongo/
 *
 * Share and Enjoy!  :-)
 */

#define DLLEXP __declspec(dllexport)trick1

#include <my_global.h>
#include <my_sys.h>
#include <mysql.h>
#include <ctype.h>
#include <string.h>

/* On the first call, use this as the initial_value. */
#define HASH_64_INIT 0x84222325cbf29ce4ULL
/* Default for NULLs, just so the result is never NULL. */
#define HASH_NULL_DEFAULT 0x0a0b0c0d
/* Magic number for the hashing. */
#define FNV_64_PRIME 0x100000001b3ULL

/* Prototypes */

extern "C" {
   ulonglong hash64(const void *buf, size_t len, ulonglong hval);
  DLLEXPtrick2
   my_bool fnv_64_init( UDF_INIT* initid, UDF_ARGS* args, char* message );
  DLLEXPtrick3
   ulonglong fnv_64(UDF_INIT *initid, UDF_ARGS *args, char *is_null, char *error );
}

Right click on Solution 'fnv_udf' and select Build Solution. Copy the resulting P:\dev\apps\db\maatkit-7540\udf\Release\fnv_udf.dll to P:\dev\apps\db\mysql-5.5\lib\plugin which is the default plugin-dir.

Finally add this functionality to the master with (in case of an upgrade just restart the servers and skip create function step):

mysql -u root -p
mysql> show variables like "%plugin%";
mysql> create function fnv_64 returns integer soname 'fnv_udf.dll';
mysql> select * from mysql.func;
mysql> select fnv_64('Share and Enjoy!', ':-)');
mysql> quit

Note

Once it is installed, it is preferred by mk-table-checksum.

Verify that this function is replicated to the slave mysql -P 3307 -u root -p with select fnv_64('Share and Enjoy!', ':-)');.

trick10.1.6.2. Online replication consistency check

Perform an online replication consistency check, or checksum MySQL tables efficiently on one or many servers with mk-table-checksum tool.

Create a checksum user as follows:

mysql -u root -p
mysql> grant select, process, super, replication slave on *.* 
    ->  to 'checksum-user'@'192.168.0.%' identified by 'password';
mysql> grant create, select, insert, update, delete on test.checksum 
    ->  to 'checksum-user'@'192.168.0.%';
mysql> flush privileges;
mysql> select host,user from mysql.user;
mysql> quit

Important

Changes in MySQL 5.5.25 (30 May 2012) Replication: The SHOW BINARY LOGS statement (and its equivalent SHOW MASTER LOGS) may now be executed by a user with the REPLICATION CLIENT privilege. (Formerly, the SUPER privilege was necessary to use either form of this statement.).

Create a batch file for the two consistency check statements P:\dev\apps\windows\batch\mysql-checksum.bat:

@echo off

@echo create checksums
call mk-table-checksum --chunk-size 500000 --algorithm BIT_XOR ^
                       --create-replicate-table --empty-replicate-table ^
                       --replicate test.checksum --databases %1 ^
                       dev.net,P=3306 -u checksum-user --ask-pass

@echo Exit Code: %ERRORLEVEL%

@echo verify checksums
call mk-table-checksum --replicate test.checksum --recursion-method hosts ^
                       --replicate-check 1 h=dev.net,P=3306 ^
                       -u checksum-user --ask-pass

@echo Exit Code: %ERRORLEVEL%

Important

With show slave status\G verify that the slave is still running (see Slave_IO_Running and Slave_SQL_Running) or ran into an error (see Last_Errno, Slave_IO_Running and Slave_SQL_Running).

Run mysql-checksum.bat mysql to verify the mysql database tables.

trick

Note

You'll notice a difference in the mysql.tables_priv checksums. This is a result of the fact that the grantor in this table isn't replicated to the slave (as you can see with select * from mysql.tables_priv;). Read the following section to see how this can be fixed.

trick10.1.6.3. Synchronize tables efficiently

The tool mk-table-sync is designed to do one-way synchronization of data (two-way sync is planned for the future). It is a good idea to back up your data and run mk-table-sync with --test first, to see what will happen. If you want to see which rows are different without changing the tables, use --print instead of --execute.

Create a sync user as follows:

mysql -u root -p
mysql> grant super, process, replication client, select, insert, update, delete 
    ->  on *.* to 'sync-user'@'localhost' identified by 'password';
mysql> flush privileges;
mysql> select host,user from mysql.user;
mysql> quit

Find out which databases and tables will be synchronized with mk-table-sync --chunk-size 500000 --replicate test.checksum --sync-to-master h=localhost,P=3307 -u sync-user --ask-pass --dry-run.

Note

The actual number of changes will all be 0 because the statements aren't executed.

In case of the checksum error of the prior section this will result in mysql.tables_priv.

To first preview the the specific changes and then synchronize the slave create the following batch file P:\dev\apps\windows\batch\mysql-slave-sync.bat:

@echo off

@echo preview
call mk-table-sync --chunk-size 500000 --replicate test.checksum ^
                   --sync-to-master ^
                   --databases %1 h=localhost,P=3307 ^
                   -u sync-user --ask-pass --print --transaction

if %ERRORLEVEL% == 0 goto end

@echo execute
call mk-table-sync --replicate test.checksum --sync-to-master ^
                   --databases %1 h=localhost,P=3307 ^
                   -u sync-user --ask-pass --execute --transaction --verbose

:end
@echo Exit Code: %ERRORLEVEL%

Run the synchronization with mysql-slave-sync.bat mysql.

Verify the synchronization with mysql-checksum.bat mysql.

trick10.1.6.4. Replication errors

The tool mk-slave-restart watches and restart MySQL replication after errors and tries to skip statements that cause errors.

To start this sentinel for the slave after an error use the following batch file P:\dev\apps\windows\batch\mysql-slave-start-sentinel.bat:

@echo off

if not exist "P:\dev\logs\db\mysql\slave-sentinel" goto slaveRestart

del P:\dev\logs\db\mysql\slave-sentinel

:slaveRestart
mk-slave-restart --verbose --sentinel P:/dev/logs/db/mysql/slave-sentinel ^
                 -h localhost -P 3307 -u root --ask-pass

When the slave is successfully restarted signal the sentinel to stop with the following batch file P:\dev\apps\windows\batch\mysql-slave-stop-sentinel.bat:

@echo off
mk-slave-restart --verbose --sentinel P:/dev/logs/db/mysql/slave-sentinel ^
                 -h localhost -P 3307 -u root --ask-pass --stop

trick10.1.6.5. Measure slave lag accurately

The tool mk-heartbeat is a two-part replication delay monitoring system that doesn't require the slave to be working.

Create a heartbeat table as follows:

mysql -u root -p
mysql> create table test.heartbeat (
    ->  id int      not null primary key,
    ->  ts datetime not null
    -> );
mysql> insert test.heartbeat (id,ts) VALUES (1,now());
mysql> select * from test.heartbeat;
mysql> quit

Create a monitor user as follows:

mysql -u root -p
mysql> grant select, insert, update, delete on test.heartbeat 
    ->  to 'monitor-user'@'192.168.0.%' identified by 'password';
mysql> flush privileges;
mysql> select host,user from mysql.user;
mysql> quit

Run mysql-checksum.bat mysql and mysql-slave-sync.bat mysql (see also grantor note).

Create a batch file for the heartbeat on the master P:\dev\apps\windows\batch\mysql-heartbeat.bat:

@echo off
mk-heartbeat -D test --update -h dev.net -u monitor-user --ask-pass

Create a batch file for the heartmonitor on the slave P:\dev\apps\windows\batch\mysql-heartmonitor.bat:

@echo off
mk-heartbeat -D test --monitor -h dev.net -P 3307 -u monitor-user --ask-pass

trick10.1.6.6. Slave delay

The tool mk-slave-delay implements an oft-requested replication feature: the ability to make a slave lag its master, a.k.a. scheduling binlog events for some time in the future.

Create a jetlag user as follows:

mysql -u root -p
mysql> grant super, replication client on *.* to 'jetlag-user'@'192.168.0.%' 
    ->  identified by 'password';
mysql> flush privileges;
mysql> select host,user from mysql.user;
mysql> quit

Create a batch file for the delay on the slave P:\dev\apps\windows\batch\mysql-jetlag.bat:

@echo off
mk-slave-delay --delay 1h --interval 1m u=jetlag-user,h=dev.net,P=3307 ^
               --ask-pass --quiet

When mysql-jetlag.bat is started use mysql-heartbeat.bat and mysql-heartmonitor.bat to monitor the delay, which should end up between 1h (= delay) and 1h + 1m (= delay + interval). Go all out with mysql-checksum.bat mysql. All jobs can be killed with Ctrl+C but it might take a moment to register.

trick10.1.7. SQL Manager installation guide

EMS SQL Manager for MySQL Freeware is an excellent freeware graphical tool for MySQL Server administration. It has minimal required set of instruments for those users who are new to MySQL server and need only its basic functionality.

Download the SQLManager for MySQL archive: mymanager_lite.zip [version 5.2.0.1].

Extract this .zip file to C:\tmp and run the C:\tmp\MyManagerLiteSetup.exe to install SQL Manager in P:\dev\apps\db\sqlmanager.

Run the SQLManager and select DatabaseRegister Database... and enter the following settings:

  • Host name: localhost on Port: 3306.

  • User name: root.

  • Password: password and select Next.

  • Database name: mysql and click Finish.

trick10.1.8. Navicat installation guide

Navicat is a fast, reliable and affordable Database Administration tool purpose-built for simplifying database management and reducing administrative costs. Designed to meet the needs of database administrators, developers, and small and medium businesses, Navicat is built with an intuitive GUI which lets you create, organize, access and share information in a secure and easy way.

Download the Win32 binary: navicat091_lite_en.exe [version 9.1.11].

Note

At the time of writing there isn't a lite version available anymore.

Run this .exe file to install Navicat Lite in P:\dev\apps\db\navicat.

Run the Navicat and select FileNew Connection...MySQL... and enter the following settings:

  • Connection name: MySQL.

  • Host name/IP address: localhost.

  • Port: 3306.

  • User name: root.

  • Password: password and click Ok.

trickChapter 11. Version Control System

trick11.1. Git

Git is a free & open source, distributed version control system designed to handle everything from small to very large projects with speed and efficiency. Every Git clone is a full-fledged repository with complete history and full revision tracking capabilities, not dependent on network access or a central server. Branching and merging are fast and easy to do.

GitHub is a web-based hosting service for software development projects that use the Git revision control system.

trick11.1.1. Resources

trick11.1.2. Git installation guide

Download the binary: Git-1.7.9-preview20120201.exe [version 1.7.9].

Run this .exe file to install Git in P:\dev\apps\vcs\git with the following settings:

  • Use Git Bash only.

  • Checkout Windows-style, commit Unix-style line endings.

trickPress Windows Logo+Break keys to open the Windows System Properties. Select Advanced system settingsEnvironment Variables and Edit the Path to append %GIT_HOME%\bin;. Also add a New system variable GIT_HOME pointing to P:\dev\apps\vcs\git.

Verify the installation with git --version.

Now mkdir P:\dev\data\repo\git where the new project repositories will be residing. Also mkdir P:\dev\apps\vcs\git\tmp to prevent the following message bash.exe: warning: could not find /tmp, please create.

trick11.1.2.1. Git bash home directory

Right-click on the shortcut for Git Bash and change PropertiesStart in from %HOMEDRIVE%%HOMEPATH% to W:\projects.

Tip

Auto-completion should be preconfigured during installation. When typing a git command press TAB for auto-completion when it should be obvious what the statement will be. Type TAB twice to get the suggestions when isn't. For example git clo versus git cl (with suggestions: clean clone).

trick11.1.2.2. Global settings

Start Git Bash and setup user specific global settings with (see also C:\Users\<username>\.gitconfig):

git config --global user.name "Jene Jasper"
git config --global user.email jjasper@company.org

git config --global core.editor \
    "'P:/dev/apps/editor/notepad++/notepad++.exe' \
     -multiInst -noPlugins -nosession -notabbar"

git config --global branch.autosetuprebase always

git config --list

trick11.1.2.3. External diff tool

To be able to use WinMerge as the diff tool add the following:

git config --global diff.tool winmerge
git config --global difftool.winmerge.cmd \
    "winmerge.sh \"\$LOCAL\" \"\$BASE\" \"\$REMOTE\""
git config --global difftool.prompt false

Create the following wrapper P:\dev\apps\windows\batch\winmerge.sh:

#!/bin/sh

# Passing the following parameters to difftool:
#  LOCAL BASE REMOTE

diffPreImage=$1
diffFileName=$2
diffPostImage=$3

NULL="/dev/null"

if [ "$diffPostImage" = "$NULL" ] ; then
    echo "removed: $diffFileName"
elif [ "$diffPreImage" = "$NULL" ] ; then
    echo "added: $diffFileName"
else
    echo "changed: $diffFileName"
    "P:/dev/apps/editor/winmerge/WinMergeU.exe" -e -u \
     -dl "Working copy $diffFileName" \
     -dr "Original $diffFileName" "$diffPostImage" "$diffPreImage" 
fi

trick11.1.2.4. External merge tool

To be able to use KDiff3 as the merge tool add the following:

git config --global merge.tool kdiff
git config --global mergetool.kdiff.cmd \
  '3waymerge.sh "$PWD/$LOCAL" "$PWD/$BASE" "$PWD/$REMOTE" "$PWD/$MERGED"'
git config --global mergetool.kdiff.trustExitCode false
git config --global mergetool.kdiff.keepBackup false
git config --global mergetool.prompt false

Create the following wrapper P:\dev\apps\windows\batch\3waymerge.sh:

#!/bin/sh

# Passing the following parameters to mergetool:
#  LOCAL BASE REMOTE MERGED

currentBranch=$1
commonBaseMerge=$2
toBeMerged=$3
resultOfMerge=$4

if [ -f $commonBaseMerge ]
then
    # KDiff3 will display eol choices (if Windows: CRLF, if Unix LF)
    "P:/dev/apps/editor/kdiff3/kdiff3.exe" \
    -m "$commonBaseMerge" "$currentBranch" "$toBeMerged" \
    -o "$resultOfMerge"
else
    # KDiff3 however does know how to merge based on 2 files (not just 3)
    "P:/dev/apps/editor/kdiff3/kdiff3.exe" \
    -m "$commonBaseMerge" "$toBeMerged" \
    -o "$resultOfMerge"
fi

trick11.1.2.5. Ignores template

Create the following ignores template P:\dev\data\repo\.gitignore:

#general
*.bak
*~
*.log

#compiled
*.com
*.class
*.dll
*.exe
*.o
*.so

#eclipse
.classpath
.project
.settings/

#maven
target/

#cvs
CVS/
.cvsignore

#subversion
.svn/

trick11.1.3. Test drive

With above settings in place in C:\Users\<username>\.gitconfig:

[user]
  name = Jene Jasper
  email = jjasper@company.org
[core]
  editor = 'P:/dev/apps/editor/notepad++/notepad++.exe' ...
[diff]
  tool = winmerge
[difftool "winmerge"]
  cmd = winmerge.sh \"$LOCAL\" \"$BASE\" \"$REMOTE\"
[difftool]
  prompt = false
[merge]
  tool = kdiff
[mergetool "kdiff"]
  cmd = 3waymerge.sh \"$PWD/$LOCAL\" \"$PWD/$BASE\" \"$PWD/$REMOTE\" ...
  trustExitCode = false
  keepBackup = false
[mergetool]
  prompt = false

A slightly changed example based on Setting up diff and merge tools for Git on Windows to see everything in action.

Start Git Bash and create a sample project test-drive with ignores in W:\projects\test-drive as follows:

mkdir test-drive
cd test-drive
git init
cp /p/dev/data/repo/.gitignore .
git add .gitignore

Create the following file W:\projects\test-drive\hello.txt:

Hello world!
Second line.
Third Line.

Stage hello.txt also and commit both files with:

git status
git add hello.txt
git status
git commit -m 'initial commit.'
git status
git log --pretty=oneline

Create a new branch and check it out in one go:

git checkout -b hello-git
git status

Change the branched W:\projects\test-drive\hello.txt as follows:

Hello Git!
Second line.
3rd Line.

Skip the staging command by committing the change immediately and switch back to the master branch:

git status
git commit -a -m 'branch commit.'
git log --pretty=oneline
git status
git checkout master
git status

Append text to the head revision first line and change third line uppercase 'L' in W:\projects\test-drive\hello.txt as follows:

Hello world! Hello indeed.
Second line.
Third line.

Commit this change to the master branch and try to merge both branches:

git status
git commit -a -m 'head commit.'
git status
git merge hello-git
git status
git diff

Use KDiff3 to fix the merge conflicts:

git mergetool

For the first conflict select the content of both the file C and the file B with Ctrl+3 followed by Ctrl+2. Move to the next conflict with Ctrl+Down and select the content of the file B with Ctrl+2. Finally combine the first line copies of B and C in the output file to look like:

Hello Git! Hello indeed.
Second line.
Third line.

Quit KDiff3 with Ctrl+Q and verify the resulting patch or diff using WinMerge:

git status
git diff --cached
git difftool --cached
git log --pretty=oneline
git commit -m 'merged file.'
gitk
git branch -D hello-git
gitk

trick11.1.4. Apache configuration

Git-http-backend is a simple CGI program to serve the contents of a Git repository to Git clients accessing the repository over http and https protocols. The program supports clients fetching using both the smart HTTP protocol and the backwards-compatible dumb HTTP protocol, as well as clients pushing using the smart HTTP protocol.

Define a macro to delegate the handling of all URLs whose path portions begin with /git-repo/ to use this Smart HTTP Transport with the following include 1 just after httpd-macro.conf in P:\dev\apps\httpserver\apache-conf\httpd.conf:

# Apache Macro
Include ../apache-conf/httpd-macro.conf
Include ../apache-conf/httpd-git-macro.conftrick1

with the following content in P:\dev\apps\httpserver\apache-conf\httpd-git-macro.conf:

<IfModule mod_macro.c>
<IfModule alias_module>
<IfModule env_module>
    <Macro GitRepos $git_uri $project_root>
        <Location $git_uri>
            Include ../apache-conf/httpd-realm.conf
        </Location>

        SetEnv GIT_PROJECT_ROOT $project_root
        SetEnv GIT_HTTP_EXPORT_ALL

        AliasMatch \
          ^$git_uri/(.*/objects/[0-9a-f]{2}/[0-9a-f]{38})$ \
          $project_root/$1
        AliasMatch \
          ^$git_uri/(.*/objects/pack/pack-[0-9a-f]{40}.(pack|idx))$ \
          $project_root/$1

        ScriptAliasMatch \
          (?x)^$git_uri/(.*/(HEAD|info/refs|objects/info/[^/]+ \
                             |git-(upload|receive)-pack))$ \
          P:/dev/apps/vcs/git/libexec/git-core/git-http-backend.exe/$1
    </Macro>
</IfModule>
</IfModule>
</IfModule>

Use 1 this macro in P:\dev\apps\httpserver\apache-conf\httpd-vhosts.conf:

<VirtualHost *:80>
    ...

    <IfModule proxy_module>
    <IfModule proxy_http_module>
        ...

        <Proxy *>
            ...
        </Proxy>
        
        # Git
        Use GitRepos /git-repo P:/dev/data/repo/gittrick1
    </IfModule>
    </IfModule>
</VirtualHost>

Restart the Apache HTTP Server.

You may need to reboot the server for the Path setting for GIT_HOME to take effect.

trick11.1.4.1. Git repository

Also define in this macro to delegate the handling of all URLs whose path portions begin with /git-repo/ to the CGI (Common Gateway Interface) of GitWeb 1 which allows browsing a Git repository (or a set of Git repositories) using a web browser in the above created file P:\dev\apps\httpserver\apache-conf\httpd-git-macro.conf:

<IfModule mod_macro.c>
<IfModule mod_cgi.c>trick1
<IfModule alias_module>
<IfModule env_module>
    <Macro GitRepos $git_uri $project_root $gitweb_conftrick1>
        ...

        ScriptAliasMatch \
          ...
          P:/dev/apps/vcs/git/libexec/git-core/git-http-backend.exe/$1

        SetEnv GITWEB_CONFIG P:/dev/data/httpserver/home/git/$gitweb_conftrick1

        Alias $git_uri/static P:/dev/apps/vcs/git/share/gitweb/statictrick1

        ScriptAlias $git_uri P:/dev/apps/vcs/git/share/gitweb/gitweb.cgitrick1
    </Macro>
</IfModule>
</IfModule>
</IfModule>trick1
</IfModule>

with the following content in P:\dev\data\httpserver\home\git\gitweb.conf (see also gitweb/README):

$projectroot = "/p/dev/data/repo/git";
$stylesheet = "git-repo/static/gitweb.css";
$logo = "git-repo/static/git-logo.png";
$favicon = "git-repo/static/git-favicon.png";
$javascript = "git-repo/static/gitweb.js";
$projects_list_description_width = 75

Supply the extra parameter for $gitweb_conf filename in P:\dev\apps\httpserver\apache-conf\httpd-vhosts.conf:

        # Git
        Use GitRepos /git-repo P:/dev/data/repo/git gitweb.conf

trick11.1.4.2. GitWeb Perl implementation

Because GitWeb isn't working with ActivePerl (see also perl.reg) configure it to use the supplied Perl implementation of mysysGit in P:\dev\apps\vcs\git\share\gitweb\gitweb.cgi:

#!/usr/bin/perlP:/dev/apps/vcs/git/bin/perl.exetrick1

But this one is missing the CGI.pm module. Just copy it from ActivePerl:

copy P:\dev\apps\prg\perl-5.12.4.1205\lib\CGI.pm ^
     P:\dev\apps\vcs\git\share\gitweb

xcopy /E /I P:\dev\apps\prg\perl-5.12.4.1205\lib\CGI ^
            P:\dev\apps\vcs\git\share\gitweb\CGI

When the Apache HTTP Server is restarted you should be able to browse the Git Repository at http://dev.net/git-repo.

trick11.1.4.3. Git private repository

With the above macro setup, it is possible to simply add a private Git repository that is only available at for example http://localhost/git-private only in P:\dev\apps\httpserver\apache-conf\httpd-vhosts.conf:

NameVirtualHost *:80

<VirtualHost *:80>
    ...
</VirtualHost>

<VirtualHost 127.0.0.1:80>
    Use GitRepos /git-private P:/dev/data/repo/private/git gitweb-private.conf
</VirtualHost>

with its own GitWeb configuration file P:\dev\data\httpserver\home\git\gitweb-private.conf:

$projectroot = "/p/dev/data/repo/private/git";
$stylesheet = "git-private/static/gitweb.css";
$logo = "git-private/static/git-logo.png";
$favicon = "git-private/static/git-favicon.png";
$javascript = "git-private/static/gitweb.js";
$projects_list_description_width = 75

trick11.1.4.4. Repository styling

Style the repository with for example the gitweb-theme (an alternative theme for GitWeb, strongly inspired by GitHub):

cd /d P:\dev\data\httpserver\home\git
git clone git://github.com/kogakure/gitweb-theme

Configure the theme in P:/dev/data/httpserver/home/git/gitweb.conf:

$stylesheet = "git-repo/staticgitweb-theme/gitweb.css";
...
$javascript = "git-repo/staticgitweb-theme/gitweb.js";

Point Apache HTTP Server to the correct location in P:\dev\apps\httpserver\apache-conf\httpd-git.conf:

    Alias /git-repo/static P:/dev/apps/vcs/git/share/gitweb/static
    Alias /git-repo/gitweb-theme P:/dev/data/httpserver/home/git/gitweb-themetrick1

When the Apache HTTP Server is restarted you should be able to browse the Git Repository with a new theme at http://dev.net/git-repo.

trick11.1.5. Defining a project

Create a shell script P:\dev\apps\windows\batch\git-create-repo.sh:

#!/bin/bash

if [ $# != 3  ]
then
  echo "Usage: git-create-repo <git-repo-location> <project-name> \"<project-description>\"."
  exit 9
else
  git_repo="$1"
  project_name="$2"
  project_description="$3"

  echo "Project request for $project_name - $project_description"
  if [ -d "$git_repo" ]
  then
    echo "Located Git repository at $git_repo"
  else
    echo "Create Git repository at $git_repo"
    mkdir $git_repo || exit 1
  fi
  if [ -d "$git_repo/$project_name" ]
  then
    echo "Project $project_name already exists."
    exit 2
  else
    echo "Create project $project_name"
    cd $git_repo
    git init --bare $project_name
    
    echo "Set project description to $project_description"
    cd $project_name
    echo "$project_description" > description

    echo "Set description $project_description"
    git config http.receivepack true

    echo "Disable auto-converting CRLF line endings into LF"
    git config core.autocrlf false

    echo "Make 'git pull' on master always use rebase"
    git config branch.master.rebase true

    echo "Setup rebase for every tracking branch"
    git config branch.autosetuprebase always
    tmp=${TMPDIR-/tmp}
    tmp=$tmp/git-clone.$RANDOM.$RANDOM.$RANDOM.$$
    echo "Create temporary clone of project $project_name in $tmp"
    mkdir $tmp || exit 3
    cd $tmp
    git clone $git_repo/$project_name $tmp/$project_name
    cd $project_name
    echo "Add .gitignore to project"
    cp P:/dev/data/repo/.gitignore $tmp/$project_name
    git config user.name "dev.net GitWeb"
    git config user.email gitweb.noreply@company.org
    git config core.autocrlf false     (see also note below about line endings)
    git add .gitignore
    git commit -am "initial commit."
    git push origin master
    echo "Cleanup temporary clone of project $project_name in $tmp"
    cd ../..
    rm -rf $tmp || exit 4
  fi
fi
trick

Note

Line endings… the scourge of every Windows-based developer that tries to mingle with linux- or mac-based developers. Though most modern text editors can handle both newline types without issue, git is not as graceful. Combined with Eclipse issue 301775: EGit/JGit ignores the core.autocrlf flag which may be quite inconvenient for Windows users the command git config core.autocrlf false is added to the above script. The article linked at the beginning of this note also supplies information to fix this setting issue and how to reset your repos at a later stage.

Create a new bare repository with the following command git-create-repo.sh P:/dev/data/repo/git dpl-manual.git "Production Development Line manual".

trick11.1.5.1. GitWeb enhancement

Might as well use above defined script git-create-repo.sh to add support for creating repositories to GitWeb by patching P:\dev\apps\vcs\git\share\gitweb\gitweb.cgi:

@@ -760,6 +760,8 @@ our @cgi_param_mapping = (
   extra_options => "opt",
   search_use_regexp => "sr",
   ctag => "by_tag",
+  new_project_name => "pn",
+  new_project_description => "pd",
   # this must be last entry (for manipulation from JavaScript)
   javascript => "js"
 );
@@ -799,6 +801,7 @@ our %actions = (
   "opml" => \&git_opml,
   "project_list" => \&git_project_list,
   "project_index" => \&git_project_index,
+  "create" => \&git_project_create,
 );
 
 # finally, we have the hash of allowed extra_options for the commands that
@@ -976,7 +979,7 @@ sub evaluate_path_info {
 
 our ($action, $project, $file_name, $file_parent, $hash, $hash_parent, $hash_base,
      $hash_parent_base, @extra_options, $page, $searchtype, $search_use_regexp,
-     $searchtext, $search_regexp);
+     $searchtext, $search_regexp, $new_project_name, $new_project_description);
 sub evaluate_and_validate_params {
   our $action = $input_params{'action'};
   if (defined $action) {
@@ -1075,6 +1078,26 @@ sub evaluate_and_validate_params {
     }
     $search_regexp = $search_use_regexp ? $searchtext : quotemeta $searchtext;
   }
+
+  our $new_project_name = $input_params{'new_project_name'};
+  if (defined $new_project_name) {
+    if (length($new_project_name) < 1) {
+      die_error(403, "Project name is a required parameter");
+    }
+    if ($new_project_name =~ m/[^a-zA-Z0-9-]/) {
+      die_error(400, "Invalid project name parameter");
+    }
+  }
+
+  our $new_project_description = $input_params{'new_project_description'};
+  if (defined $new_project_description) {
+    if (length($new_project_description) < 1) {
+      die_error(403, "Project description is a required parameter");
+    }
+    if ($new_project_description =~ m/[^a-zA-Z0-9 -]/) {
+      die_error(400, "Invalid project description parameter");
+    }
+  }
 }
 
 # path to the current git repository
@@ -1136,7 +1159,7 @@ sub dispatch {
   if (!defined($actions{$action})) {
     die_error(400, "Unknown action");
   }
-  if ($action !~ m/^(?:opml|project_list|project_index)$/ &&
+  if ($action !~ m/^(?:opml|project_list|project_index|create)$/ &&
       !$project) {
     die_error(400, "Project needed");
   }
@@ -6005,9 +6028,6 @@ sub git_project_list {
   }
 
   my @list = git_get_projects_list();
-  if (!@list) {
-    die_error(404, "No projects found");
-  }
 
   git_header_html();
   if (defined $home_text && -f $home_text) {
@@ -6020,10 +6040,29 @@ sub git_project_list {
         $cgi->textfield(-name => "s", -value => $searchtext) . "\n" .
         "</p>" .
         $cgi->end_form() . "\n";
-  git_project_list_body(\@list, $order);
+  if (!@list) {
+    print "<center>\n".
+          "<b>No projects found</b><br />\n".
+          "</center>\n<br />\n";
+  }
+  else {
+    git_project_list_body(\@list, $order);
+  }
+  git_project_create_form();
   git_footer_html();
 }
 
+sub git_project_create_form {
+  print $cgi->startform(-method => "get") .
+        "<p align=\"right\" class=\"projcreate\">Project Name:\n" .
+        $cgi->textfield(-name => "pn", -value => $searchtext) . "\n" .
+        "Description:\n" .
+        $cgi->textfield(-name => "pd", -value => $searchtext) . "\n" .
+        $cgi->submit(-name => "a", -value => "create") . "\n" .
+        "</p>" .
+        $cgi->end_form() . "\n";
+}
+
 sub git_forks {
   my $order = $input_params{'order'};
   if (defined $order && $order !~ m/none|project|descr|owner|age/) {
@@ -6069,6 +6108,39 @@ sub git_project_index {
   }
 }
 
+sub git_project_create {
+  if (!defined $new_project_name) {
+    die_error(400, "Project name is empty");
+  }
+  if (!defined $new_project_description) {
+    die_error(400, "Project description is empty");
+  }
+
+  my $full_project_name = "$new_project_name.git";
+
+  my @result = `git-create-repo.sh $projectroot $full_project_name "$new_project_description"`;
+  my $exit_value = $? >> 8;
+  $result[-1] =~ s/\n/ /g;
+
+  if ($exit_value eq "9") {
+    die_error(400, "Failed to create project $full_project_name - $result[-1]");
+  }
+  elsif ($exit_value eq "1") {
+    die_error(400, "Unable to create Git repository directory - $result[-1]");
+  }
+  elsif ($exit_value eq "2") {
+    die_error(400, "Project $full_project_name already exists.");
+  }
+  elsif ($exit_value eq "3") {
+    die_error(400, "Couldn't create temporary clone for initial commit - $result[-1]");
+  }
+  elsif ($exit_value eq "4") {
+    die_error(400, "Couldn't cleanup temporary clone for initial commit - $result[-1]");
+  }
+
+  git_project_list();
+}
+
 sub git_summary {
   my $descr = git_get_project_description($project) || "none";
   my %co = parse_commit("HEAD");

Note

Make sure git-create-repo.sh is available on the BATCH_HOME path.

Now it is possible to create a remote repository with GitWeb. Just enter a project name (without .git suffix) and description by calling http://dev.net/git-repo?pn=gitweb&pd=GitWeb+CGI+enhancement&a=create direct or through the user interface enhancement:

trick
GitWeb enhancement

Figure 11.1. GitWeb enhancement


trick11.1.6. Working on a project

Ask Git to clone a copy of a repository with the following batch file P:\dev\apps\windows\batch\git-clone.bat:

@echo off

if not "%2"=="" goto cloneRepo

echo Usage: git-clone ^<username^> ^<projectname^>
goto end

:cloneRepo
cd /d W:\projects
if exist \projects\%2 ren "%2" "%2.old"
git clone http://%1@dev.net/git-repo/%2
cd %2
git config core.autocrlf false            (see also note about line endings)

:end

Clone the remote repository with the following command git-clone jjasper dpl-manual.

Now you have a personal copy of the remote repository in a new directory named W:\projects\dpl-manual. You can edit the files in your working copy and then commit and push those changes back into the remote repository.

Other useful Git command options are:

  • git help <command> for more information on a specific command.

  • git branch to list, create, or delete branches.

  • git status to list files changed in working directory.

  • git add file contents to the index aka staging area.

  • git checkout a branch or paths to the working directory.

  • git commit record (or --amend) changes to the local repository (for example git commit -am "use -a to skip add of modified file to staging area first.").

  • git fetch latest changes from origin to local repository.

  • git pull latest changes from origin and then merge into your current branch.

  • git push your work back up to the origin.

  • git diff displays changes between commits, commit and working directory, etc.

  • git mv is a convenience function for renaming files.

  • git revert some existing commits.

  • git merge joins two or more development histories together.

  • git rebase takes all the changes that were committed on one branch and replays them on another one. Do not rebase commits that you have pushed to a public repository.

Tip

Currently the design of the Git staging area only permits files to be listed. If you really need a directory to exist in checkouts you should create a file in it. A .gitignore file works well for this purpose, you can leave it empty or fill in the names of files you expect to show up in the directory and don't want to check-in (see also MarkEmptyDirs).

trick11.2. FishEye

Your source code repository contains an abundance of useful information that is not easy to extract, comprehend or keep up to date. FishEye painlessly opens up your repository to help you better understand your changing source.

trick11.2.1. Resources

trick11.2.2. FishEye installation guide

Download the archive: fisheye-2.7.13.zip [version 2.7.13].

Extract this .zip file to P:\dev\apps\vcs.

trickPress Windows Logo+Break keys to open the Windows System Properties. Select Advanced system settingsEnvironment Variables and Edit the Path to append %FISHEYE_HOME%\bin;. Also add a New system variable FISHEYE_HOME pointing to P:\dev\apps\vcs\fecru-2.7.13.

Verify the installation with fisheyectl.bat run. Terminate the server with Ctrl+C.

Warning

If you now notice that FishEye tries to start spontaneously in its own Windows Command Processor (cmd.exe) when the server is rebooted, you might have some startup setting that triggers the start.bat file. In my case it was the auto-start of the Task Manager during boot up. Just delete the start.bat, stop.bat and run.bat because they redirect to fisheyectl.bat anyway.

Terminate the server with Ctrl+C.

trickFor the ease of future upgrades press Windows Logo+Break keys to open the Windows System Properties. Select Advanced system settingsEnvironment Variables and add a New system variable FISHEYE_INST pointing to P:\dev\data\vcs\fisheye. And perform the following steps:

  • mkdir %FISHEYE_INST%

  • move P:\dev\apps\vcs\fecru-2.7.13\config.xml P:\dev\data\vcs\fisheye

  • mkdir %FISHEYE_INST%\lib

  • move P:\dev\apps\vcs\fecru-2.7.13\var P:\dev\data\vcs\fisheye

  • Start FishEye with fisheyectl start. When you see the message Please visit http://my.atlassian.com terminate FishEye with fisheyectl stop. Your config.xml in P:\dev\data\vcs\fisheye will now contain a license SID. This SID is required to retrieve a new license from my.atlassian.com.

trick11.2.3. FishEye configuration

Restart FishEye again with fisheyectl start. Verify that the server is running in your browser at http://localhost:8060.

When you access FishEye for the first time you will be asked for an administrator password and FishEye and Crucible licenses.

Note

Skip Connect to JIRA for now.

If you need to reset the administrator password, delete the admin-hash in the config element of your config.xml.

Connect to the FishEye Admin GUI and configure FishEye.

trick11.2.3.1. Repository Settings

Select RepositoriesNative Repository AccessAdd Existing... with:

  • Repository type: Git.

  • Name: dpl-manual.

  • Description: Production Development Line manual and click Next.

  • Repository Location: http://fisheye@dev.net/git-repo/dpl-manual.git (see also Section 7.1.4.1, “Authentication, authorization and access control”).

  • Authentication Style: Password for http(s).

  • Password: password and click Show advanced settings.

  • Rename Detection: copies and click Next.

  • Store Diff Info: enabled.

  • Enable Repository After Adding:disabled, click Test Connection and Add this repository when Connection succeeded.

Select RepositoriesNative Repository AccessAdd Existing... with:

  • Repository type: Git.

  • Name: gitweb.

  • Description: GitWeb CGI enhancement and click Next.

  • Repository Location: http://fisheye@dev.net/git-repo/gitweb.git (see also Section 7.1.4.1, “Authentication, authorization and access control”).

  • Authentication Style: Password for http(s).

  • Password: password and click Show advanced settings.

  • Rename Detection: copies and click Next.

  • Store Diff Info: enabled.

  • Enable Repository After Adding:disabled, click Test Connection and Add this repository when Connection succeeded.

Select RepositoriesNative Repository AccessAdd Existing... with:

  • Repository type: Subversion.

  • Name: svn.

  • Description: Subversion Repository and click Next.

  • SVN URL: http://localhost/svn-repo.

  • Username: fisheye (see also Section 7.1.4.1, “Authentication, authorization and access control”).

  • Password: password and click Show advanced settings.

  • Charset: default (UTF-8).

  • Initial Import: Do not Import.

  • Use Built-in Symbolic Rules: enabled.

  • And then Apply the Following Rules: /project/trunk/..., /project/branches/NAME/..., /project/tags/NAME/... and click Next.

  • Store Diff Info: enabled.

  • Enable Repository After Adding:disabled, click Test Connection and Add this repository when Connection succeeded.

Select RepositoriesNative Repository AccessAdd Existing... with:

  • Repository type: CVS.

  • Name: cvs.

  • Description: CVS Repository and click Next.

  • CVS dir: P:\dev\data\repo\cvs and click Show advanced settings.

  • Charset: UTF-8 and click Next.

  • Store Diff Info: enabled.

  • Enable Repository After Adding:disabled, click Test Connection and Add this repository when Connection succeeded.

Important

If you see the following message History file: 'P:\dev\data\repo\cvs\CVSROOT\history' does not exist. see Section B.1.2.3.3, “History log”.

To activate a repository select for example Repositoriesdpl-manualSummary and ActionsEnableStartSave.

Important

The repository types CVS and Subversion map commits based on the username. To match Git commits select AdministrationUsers and Edit for example jjasper to set his Email to the one supplied to git config --global user.email jjasper@company.org. Alternatively the user themselves can set their Email using the user specific menu Jene JasperSettingsProfile & Email.

trick11.2.3.2. Global Settings

Select Global SettingsServerWeb ServerEdit settings:

  • Web context: fisheye.

  • HTTP Bind Address: 127.0.0.1:8060.

  • Ajp13 Bind Address: 127.0.0.1:8061.

  • Allow remote API calls: On (required for JIRA FishEye integration).

  • Server timezone: Europe/Amsterdam.

  • Site URL: http://dev.net/fisheye/ and click Update.

Select Global SettingsServerMail ServerEdit config:

  • Send mail from: Server Address (below).

  • From Address: fisheye.noreply@company.org.

  • SMTP Host name: mail.dev.net and click Save, followed by Send test email.

Stop/start FishEye using fisheyectl. Verify that the server is running in your browser at http://localhost:8060/fisheye.

trick11.2.4. Apache configuration

Instruct Apache to proxy (using mod_proxy_ajp) all URLs whose path portions begin with /fisheye/ using the following P:\dev\apps\httpserver\apache-conf\httpd-vhosts.conf include 1:

<VirtualHost *:80>
    ...

    <IfModule proxy_module>
    <IfModule proxy_http_module>
        ...

        <Proxy *>
            ...
        </Proxy>

        # FishEye
        Include ../apache-conf/httpd-fisheye.conftrick1
    </IfModule>
    </IfModule>
</VirtualHost>

with the following content in P:\dev\apps\httpserver\apache-conf\httpd-fisheye.conf:

<IfModule proxy_module>
<IfModule proxy_ajp_module>
    <Location /fisheye>
        Include ../apache-conf/httpd-realm.conf  
    </Location>

    Alias /fisheye/static       "P:\dev\apps\vcs\fecru-2.7.13\content\static"

    ProxyPass /fisheye/static/  !

    ProxyPass /fisheye          ajp://localhost:8061/fisheye
    ProxyPassReverse /fisheye   ajp://localhost:8061/fisheye

#    <IfModule mod_jk.c>
#        JkMount /fisheye   fisheye
#        JkMount /fisheye/* fisheye
#    </IfModule>
</IfModule>
</IfModule>

When the Apache HTTP Server is restarted you should be able to browse FishEye at http://dev.net/fisheye.

trick11.2.4.1. Security

Next configure at the FishEye Admin GUI the Security SettingsAuthentication:

  • For Global Permissions: Global Anonymous Access and Crucible Anonymous Access select Turn Off.

  • For Built-in: Public Signup select Turn Off.

  • For Email Visibility: select Visible to logged in users only.

  • For Authentication settings click Setup AJP13 authentication:

    • Cache TTL (positive): 5 mins.

    • Auto-add: Create a FishEye user on successful login and Apply those settings.

Also configure the Repository SettingsDefaults:

  • For Permissions: Anonymous uncheck Can Read, All logged-in users check Can Read and Save changes.

Stop/start FishEye using fisheyectl. When the Apache HTTP Server is restarted you should be able to browse FishEye with your dev.net realm username and password.

Once the user, who is also the FishEye administrator, has logged in select Security SettingsAdministrators and place yourself in the Admin Users. This way you no longer need to enter the Administration Password.

On the Dashboard page click on the logged-in user and select Settings to edit the Author Mapping and Add for cvs the commiter: %USERDOMAIN%\jjasper.

trick

Tip

The HTTP Bind Address 127.0.0.1:8060 could be removed now that the AJP authentication is setup and running. In case of problems with the AJP Bind Address you will be able to reset the HTTP Bind Address by reinserting it 1 in the config.xml as follows:

<web-server context="fisheye" site-url="http://dev.net/fisheye/">
  <http bind="127.0.0.1:8060"/>trick1
  <ajp13 bind="127.0.0.1:8061"/>
</web-server>

trick11.2.5. Windows service

To restart automatically on Microsoft Windows, create a Windows service.

Download the Tanuki Java Service Wrapper archive: wrapper.zip.

Extract this .zip file to P:\dev\apps\vcs\fecru-2.7.13.

Optionally comment out the jmx entries 6 and edit the following entries 1-11 in the service wrapper configuration file P:\dev\apps\vcs\fecru-2.7.13\wrapper\conf\wrapper.conf:

# Java Additional Parameters
wrapper.java.additional.1=-server
wrapper.java.additional.2=-showversion
wrapper.java.additional.3=-Djava.awt.headless=true
wrapper.java.additional.4=-XX:MaxPermSize=192mtrick1
wrapper.java.additional.5=-Xmx512mtrick2
wrapper.java.additional.6=-Xms128mtrick3
wrapper.java.additional.7=-Dfile.encoding=UTF-8trick4
wrapper.java.additional.8=-Dfisheye.inst=%FISHEYE_INST%trick5

# JDK 1.5 Additional Parameters for jmx
#trick6wrapper.java.additional.4=-Dcom.sun.management.jmxremote
#trick6wrapper.java.additional.5=-Dcom.sun.management.jmxremote.port=4242
#trick6wrapper.java.additional.6=-Dcom.sun.management.jmxremote.authenticate=false
#trick6wrapper.java.additional.7=-Dcom.sun.management.jmxremote.ssl=false
#trick6wrapper.java.additional.8=-Dcom.sun.management.jmxremote.authenticate=false
#trick6wrapper.java.additional.9=-Dcom.sun.management.jmxremote.password.file=./wrapper/jmxremote.password
#trick6wrapper.java.additional.10=-Dwrapper.mbean.name="wrapper:type=Java Service Wrapper Control"

...

# Log file to use for wrapper output logging.
wrapper.logfile==var/log/wrapper.log%FISHEYE_INST%/var/log/wrapper.logtrick7

...

# Wrapper Windows Properties
wrapper.console.title=Fisheyedev.net FishEyetrick8

...

# Wrapper Windows NT/2000/XP Service Properties
wrapper.ntservice.name=Fisheyefisheyetrick9
wrapper.ping.timeout=300                       (see also Error "JVM appears hung" in wrapper.log)
wrapper.ntservice.displayname=Fisheyedev.net FishEyetrick10
wrapper.ntservice.description=FisheyeFishEye gives Git, Subversion and CVS a Web interface.trick11

Register the FishEye service from folder cd /d %FISHEYE_HOME% with the command: wrapper\bin\Fisheye-Install-NTService.bat (In case of an upgrade sc delete fisheye first).

Start FishEye with net start fisheye.

Note

Should the following error Error: no `server' JVM at `P:\dev\apps\prg\java\jre...\bin\server\jvm.dll' occur check for stray java.exe files (see tip and warning in Section 3.1.2, “JDK installation guide”)

Important

In case of the following error Startup failed: Timed out waiting for a signal from the JVM when using jdk 1.7, just use jdk 1.6 instead 1 in P:\dev\apps\vcs\fecru-2.7.13\wrapper\conf\wrapper.conf:

# Java Application
wrapper.java.command=P:\dev\apps\prg\java\jdk1.6.0_37\bin\javatrick1

trick11.2.6. Database migration

For migration from the default embedded FishEye HSQLDB database to an external database create a MySQL user called fishseye-user and database called fisheye with the following commands:

mysql -u root -p
mysql> create database fisheye character set utf8 collate utf8_bin;
mysql> grant select, insert, update, delete, create, drop, alter, index on fisheye.*
    ->  to 'fisheye-user'@'localhost' identified by 'password';
mysql> flush privileges;
mysql> select host,user from mysql.user;
mysql> select host,db,user from mysql.db;
mysql> quit

Download the Connector/J [version 5.1.18] and add the driver mysql-connector-java-5.1.18-bin.jar from the archive mysql-connector-java-5.1.18.zip to the FishEye classpath placing it into P:\dev\data\vcs\fisheye\lib. Remove the one that is already in P:\dev\apps\vcs\fecru-2.7.13\lib\dbdrivers\mysql: mysql-connector-java-5.1.10.jar. Requires a restart of FishEye to locate this new jar.

Connect to the FishEye Admin GUI and configure MySQL database.

Select Systems SettingsDatabaseEdit:

  • Test Connection of Built-In hsqldb.

  • Type: MySQL.

  • Driver Location: User Supplied - FISHEYE_INST\lib.

  • URL: jdbc:mysql://localhost/fisheye.

  • User Name: fisheye-user.

  • Password: password, Test Connection and click Save & Migrate.

trickChapter 12. Issue Tracker

trick12.1. JIRA

JIRA is a bug tracking, issue tracking, and project management application.

trick12.1.1. Resources

trick12.1.2. JIRA installation guide

Download the archive: atlassian-jira-5.0.3.zip [version 5.0.3].

Extract this .zip file to P:\dev\apps\issue.

Important

As of JIRA 4.3 'in-place database upgrades' is officially supported.

trick12.1.2.1. HTTP Binding

Change the listening ports 1 and 2 and restricted to localhost 3 by editing the configuration file P:\dev\apps\issue\atlassian-jira-5.0.3-standalone\conf\server.xml:

<Server port="80058062trick1" address="127.0.0.1"trick3 shutdown="SHUTDOWN">
  ...
  <Service name="Catalina">
    <Connector port="80808063trick2" address="127.0.0.1"trick3

trick12.1.2.2. Database settings

Create a MySQL user called jira-user and database called jira with the following commands:

mysql -u root -p
mysql> create database jira character set utf8;
mysql> grant select, insert, update, delete, create, drop, alter, index on jira.*
    ->  to 'jira-user'@'localhost' identified by 'password';
mysql> flush privileges;
mysql> select host,user from mysql.user;
mysql> select host,db,user from mysql.db;
mysql> quit

Download the Connector/J [version 5.1.18] and add the driver mysql-connector-java-5.1.18-bin.jar from the archive mysql-connector-java-5.1.18.zip to the JIRA classpath placing it into P:\dev\apps\issue\atlassian-jira-5.0.3-standalone\lib. Remove the one that is already there: mysql-connector-java-5.1.10.jar.

Create the JIRA database connection information in P:\dev\data\issue\jira\dbconfig.xml:

<?xml version="1.0" encoding="UTF-8"?>

<jira-database-config>
  <name>defaultDS</name>
  <delegator-name>default</delegator-name>
  <database-type>mysql</database-type>
  <schema-name></schema-name>
  <jdbc-datasource>
    <url>jdbc:mysql://localhost/jira?useUnicode=true&amp;characterEncoding=UTF8</url>
    <driver-class>com.mysql.jdbc.Driver</driver-class>
    <username>jira-user</username>
    <password>password</password>
    <pool-size>20</pool-size>
    <validation-query>select 1</validation-query>
  </jdbc-datasource>
</jira-database-config>

trick12.1.3. JIRA configuration

Edit the data directory by changing the following property 1 in the P:\dev\apps\issue\atlassian-jira-5.0.3-standalone\atlassian-jira\WEB-INF\classes\jira-application.properties file:

# The jira.home configuration must be set and specifies the directory
# in which JIRA will store its data files.
# This must be set to an absolute path. Relative paths are not allowed.
# Ensure that only one JIRA instance uses the selected JIRA Home.
#
jira.home = P:/dev/data/issue/jiratrick1

Note

It is possible to overwrite this value with JIRA_HOME (see also Section 12.1.5, “Windows service”).

Disable Secure Administrator Sessions by creating the following property 1 in the P:\dev\data\issue\jira\jira-config.properties file:

jira.websudo.is.disabled=truetrick1

Verify the installation by changing to cd P:\dev\apps\issue\atlassian-jira-5.0.3-standalone and running bin\startup.bat.

Verify that the server is running in your browser at http://localhost:8063. This SID is required to retrieve a new license from my.atlassian.com.

trick12.1.3.1. Required settings

You should see the JIRA setup wizard:

  1. Application properties:

    • Application Title: dev.net JIRA.

    • Mode: Private.

    • Base URL: http://dev.net/jira.

    • Automated Backups: Disable Automated Backups.

    • License Key: ... and click Next.

  2. Administrator account:

    • Username: admin.

    • Password: password.

    • Confirm: password.

    • Fullname: JIRA Administrator.

    • Email: jira.admin@company.org and click Next.

  3. Email Notification:

    • Name: JIRA SMTP Server.

    • From address: jira.noreply@company.org.

    • Email prefix: [JIRA].

    • Host Name: mail.dev.net.

    • SMTP Port: 25.

    • Username: leave empty.

    • Password: leave empty and click Finish.

You should now be required to login at http://localhost:8063 and do some Administration.

trick12.1.3.2. User, groups & roles

Users menu:

  • Select Groups and in Add Group form type:

    • Name: jira-system-administrators and click Add Group.

    For jira-system-administrators select Edit Members:

    • Under Add members to selected group(s) select user for group by clicking .

    • Check admin and click Select.

    • Next click << Join.

  • Select Users and click Add User:

    • Username: jjasper.

    • Password: password.

    • Confirm: password.

    • Full Name: Jene Jasper.

    • Email: jjasper@company.org and click Create and Edit Groups:

      • In Available Groups select jira-system-administrators / jira-administrators / jira-developers and click Join >> and << Return to viewing user 'Jene Jasper'.

  • Select Global permissions in Add Permission form choose:

    • Permission: JIRA System Administrators.

    • Group: jira-system-administrators and click Add.

    In JIRA Permissions form:

    • For JIRA System Administrators select delete the jira-administrators and confirm Delete.

  • Select User Directories and click Edit default values:

    • Default outgoing email format: html.

    • Notify users of their own changes: No and click Update.

    And Apply the email format setting for existing users.

trick12.1.3.3. Global settings

System menu:

  • Select General Configuration and click Edit Configuration:

    • Allow unassigned issues: On.

    • Accept remote API calls: On (for Eclipse Mylyn plugin support) and click Update.

      Note

      When using Mylyn and Submit failed in Eclipse with following error message JIRA could not complete this action due to a missing form token. disable Form Token Checking by creating/editing the following property 1 in the P:\dev\data\issue\jira\jira-config.properties file:

      jira.xsrf.enabled=falsetrick1
      jira.websudo.is.disabled=true
      

      Important

      Shut down JIRA first before editing P:\dev\data\issue\jira\jira-config.properties.

  • Under Advanced select Attachments and click Edit Configuration:

    • Attachment Path: Use Default Directory and click Update.

  • Under Issue Features activate Time Tracking.

  • Under Issue Features activate Issue Linking.

  • Under User Interface select Look and Feel and click Edit Configuration:

    • Time Format: HH:mm.

    • Day Format: EEEE HH:mm.

    • Complete Date/Time Format: yyyy-MM-dd HH:mm.

    • Day/Month/Year Format: yyyy-MM-dd.

    • Check Use ISO8601 standard in Date and click Update.

  • Under General Configuration click Advanced and select every Value to be edited:

    • jira.date.picker.java.format: yyyy-MM-dd and click Update.

    • jira.date.picker.javascript.format: %Y-%m-%d.

    • jira.date.time.picker.java.format: yyyy-MM-dd HH:mm.

    • jira.date.time.picker.javascript.format: %Y-%m-%d %H:%M.

  • Under User Interface select System Dashboard and click Add Gadget such as FishEye Charts:

    • FishEye URL: http://dev.net/fisheye/.

    • Repository: svn.

    • Path: /.

    • Chart Type: Line.

    • Stack Type: File Extension.

    • Refresh Interval: Every 1 Hour.

Issues menu:

  • Under Issue Types select Sub-Tasks and Enable Sub-Tasks.

trick12.1.3.4. Project

Projects menu:

  • Select Projects and in Add Project form type:

    • Name: Development Production Line manual.

    • Key: DPLMNL.

    • Project Lead: Jene Jasper and click Add.

    Click Edit Project to supply a Description: DocBook about setting up a Production Development Line. and click Update.

    Under People for Default Assignee click to change it to Unassigned and click Update.

    Under Components:

    • Name: manual with Description: The Short Story. and click Add.

    Under Versions:

    • Name: 2.0 Description: The complete picture. with expected Release Date 2011-08-31 and click Add.

trick12.1.3.5. FishEye integration

Plugins menu:

  • Under Source Control select FishEye Configuration and click Create an Application Link. In Add Application Link form type:

    • Server URL: http://dev.net/fisheye and click Next.

    • Application Name: dev.net FishEye.

    • Application Type: FishEye / Crucible and click Create.

      Select ConfigureOutgoing AuthenticationBasic Access (do not configure Trusted Applications; this will result in access without the basic user and thus a 401 response):

Return to FishEye Configuration and after clicking Refresh in the Repository Mappings block there should be a list with all known FishEye repositories. There might be no projects mapped yet. JIRA also requires Refresh Cache next to Repository List Cache when there has been any change in FishEye repositories.

To improve JIRA's responsiveness, when your users view the Source or Reviews tabs on JIRA issues, link a FishEye repository to a JIRA project via a project link. For example select ProjectsDevelopment Production Line manualSettingsConfigure Project LinksAdd Linkdev.net FishEye and in Enter link details form type:

  • Type: FishEye Repository.

  • Key: dpl-manual and click Create.

After this there should be something to see under the Repository Mappings in the FishEye Configuration.

trick12.1.3.5.1. FishEye plugin upgrade

Optionally download a higher version of the FishEye plugin and add the archive jira-fisheye-plugin-5.0.4.1.jar to JIRA by copying it into P:\dev\data\issue\jira\plugins\installed-plugins.

trick12.1.4. Apache configuration

Configure the JIRA application server to accept an ajp connection 1 on web context /jira 4 by editing the configuration file P:\dev\apps\issue\atlassian-jira-5.0.3-standalone\conf\server.xml:

<Server port="8062"  address="127.0.0.1" shutdown="SHUTDOWN">

  <Service name="Catalina">
    ...

        <!--  trick1
    <Connector port="80098064trick2" address="127.0.0.1"trick3
      enableLookups="false" redirectPort="8443" protocol="AJP/1.3" />
        -->  trick1

    <Engine name="Catalina" defaultHost="localhost">
      <Host name="localhost" appBase="webapps" ...>

        <Context path="/jiratrick4" docBase="${catalina.home}/atlassian-jira" ...>
        ...
  </Service>

  ...
</Server>

Instruct Apache to proxy all URLs whose path portions begin with /jira/ using the following P:\dev\apps\httpserver\apache-conf\httpd-vhosts.conf include 1:

<VirtualHost *:80>
    ...

    <IfModule proxy_module>
    <IfModule proxy_http_module>
        ...

        <Proxy *>
            ...
        </Proxy>

        # JIRA
        Include ../apache-conf/httpd-jira.conftrick1
    </IfModule>
    </IfModule>
</VirtualHost>

with the following content in P:\dev\apps\httpserver\apache-conf\httpd-jira.conf:

<IfModule proxy_module>
<IfModule proxy_http_module>
#<IfModule proxy_ajp_module>
    <Location /jira>
        Include ../apache-conf/httpd-realm.conf
    </Location>

    ProxyPass /jira         http://localhost:8063/jira
    ProxyPassReverse /jira  http://localhost:8063/jira
#    ProxyPass /jira         ajp://localhost:8064/jira
#    ProxyPassReverse /jira  ajp://localhost:8064/jira
#</IfModule>
</IfModule>
</IfModule>

When JIRA and the Apache HTTP Server are restarted you should be able to browse JIRA at http://dev.net/jira.

Tip

If the browser displays a 401 HTTP error then the Apache HTTP Server logged-in user doesn't exist in JIRA or the password doesn't match.

trick12.1.5. Windows service

To restart automatically on Microsoft Windows create a service as follows (In case of an upgrade sc delete jira first):

cd /d P:\dev\apps\issue\atlassian-jira-5.0.3-standalone

set CATALINA_HOME=P:\dev\apps\issue\atlassian-jira-5.0.3-standalone
set JAVA_HOME=P:\dev\apps\prg\java\jdk1.6.0_37
bin\service.bat install jira

bin\tomcat6.exe //US//jira --DisplayName="dev.net JIRA" ^
  --Description="JIRA - Issue tracking and project management." ^
  --Startup=auto

bin\tomcat6.exe //US//jira --JvmMx=768 --JvmMs=256 ^
  ++JvmOptions=-Djava.awt.headless=true;-Datlassian.standalone=JIRA

Important

JIRA doesn't support JDK 7 therefore set JAVA_HOME to jdk1.6.

Tip

As an alternative to change the additional settings of the JIRA service run: P:\dev\apps\issue\atlassian-jira-5.0.3-standalone\bin\tomcat6w.exe //ES//jira.

Start it with net start jira.

Verify the installation and the JVM memory usage at http://dev.net/jira/secure/admin/ViewSystemInfo.jspa.

trickChapter 13. Repository Manager

trick13.1. Nexus

Nexus is a Maven repository manager, created to provide reliable access to artifacts required for development and provisioning.

trick13.1.1. Resources

trick13.1.2. Nexus installation guide

Download the archive: nexus-2.0-bundle.zip [version 2.0].

Extract this .zip file to P:\dev\apps\repo.

trickPress Windows Logo+Break keys to open the Windows System Properties. Select Advanced system settingsEnvironment Variables and add the New system variables NEXUS_HOME and trickPLEXUS_NEXUS_WORK pointing to P:\dev\apps\repo\nexus-2.0 and P:\dev\data\repo\maven\nexus.

trick13.1.2.1. HTTP Binding

Configure the container for Nexus 2-3 in the Plexus property file P:\dev\apps\repo\nexus-2.0\conf\nexus.properties:

# Sonatype Nexus
# ==============
# This is the most basic configuration of Nexus.

# Jetty section
application-port=80818067trick1
application-host=0.0.0.0127.0.0.1trick2
...

# Nexus section
nexus-work=${basedir}/../sonatype-work/nexusP:\\dev\\data\\repo\\maven\\nexustrick3
runtime=${bundleBasedir}/nexus/WEB-INF

trick13.1.3. Windows service

To restart automatically on Microsoft Windows, create a Windows service. Use the Tanuki Java Service Wrapper shipped with Nexus.

Optionally edit the following entries 1-7 in the service wrapper configuration file P:\dev\apps\repo\nexus-2.0\bin\jsw\conf\wrapper.conf:

# Additional JVM parameters (tune if needed, but match the sequence of numbers!)
wrapper.java.additional.1=-Dsun.net.inetaddr.ttl=3600
wrapper.java.additional.2=-DbundleBasedir=.
wrapper.java.additional.3=-Djava.io.tmpdir=./tmp
wrapper.java.additional.4=-DjettyContext=nexus.properties
wrapper.java.additional.5=-DjettyContextIncludeKeys=bundleBasedir
wrapper.java.additional.6=-DjettyPlexusCompatibility=true
wrapper.java.additional.7=-XX:MaxPermSize=192mtrick1
wrapper.java.additional.8=-Xmx512mtrick2
wrapper.java.additional.9=-Xms128mtrick3
#wrapper.java.additional.710=-Xdebug
#wrapper.java.additional.811=-Xnoagent
#wrapper.java.additional.912=-Djava.compiler=NONE
#wrapper.java.additional.1013=-Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8000
#wrapper.java.additional.1114=-XX:+HeapDumpOnOutOfMemoryError

...

# Set up JSW Console
wrapper.console.title=Nexus OSSdev.net Nexustrick4

...

# Set up JSW as NT Service (unused on other OSes)
wrapper.ntservice.name=nexus-webappnexustrick5
wrapper.ntservice.displayname=nexusdev.net Nexustrick6
wrapper.ntservice.description=Nexus OSSNexus is a Maven repository manager.trick7

Register the Nexus service with the command: %NEXUS_HOME%\bin\nexus.bat install. Start Nexus with sc start nexus. A nexus.xml file should now be created in the P:\dev\data\repo\maven\nexus\conf folder. Verify that the server is running in your browser at http://localhost:8067/nexus.

Important

In case of the following error Startup failed: Timed out waiting for a signal from the JVM when using jdk 1.7, just use jdk 1.6 instead 1 in P:\dev\apps\repo\nexus-2.0\bin\jsw\conf\wrapper.conf:

# Set the JVM executable 
# (modify this to absolute path if you need a Java that is not on the OS path)
wrapper.java.command=P:\dev\apps\prg\java\jdk1.6.0_37\bin\javatrick1

trick13.1.4. Apache configuration

To proxy Nexus add another Virtual Host on port 81 using the following P:\dev\apps\httpserver\apache-conf\httpd-vhosts.conf include 1:

NameVirtualHost *:80

<VirtualHost *:80>
    ServerAdmin http.webmaster@company.org
    ServerName dev.net
    ErrorLog "P:/dev/logs/httpserver/dev.net-error.log"

    ...
</VirtualHost>

...

# Nexus VirtualHost
Include ../apache-conf/httpd-vhosts-nexus.conftrick1

with the following content in P:\dev\apps\httpserver\apache-conf\httpd-vhosts-nexus.conf:

NameVirtualHost *:81
Listen 81

<VirtualHost *:81>
    ServerAdmin http.webmaster@company.org
    ServerName dev.net
    ErrorLog "P:/dev/logs/httpserver/nexus-error.log"
#    CustomLog "P:/dev/logs/httpserver/nexus-access.log" common

    <IfModule proxy_module>
    <IfModule proxy_http_module>
        ProxyRequests Off
        ProxyPreserveHost On
        
        <Proxy *>
            Include ../apache-conf/httpd-access.conf
        </Proxy>

        # Nexus
        Include ../apache-conf/httpd-nexus.conf
    </IfModule>
    </IfModule>
</VirtualHost>

with the following content in P:\dev\apps\httpserver\apache-conf\httpd-nexus.conf for anonymous access:

<IfModule proxy_module>
<IfModule proxy_http_module>
    <Location /nexus>
    </Location>

    <IfModule proxy_module>
    <IfModule proxy_http_module>
        ProxyPass /nexus        http://localhost:8067/nexus
        ProxyPassReverse /nexus http://localhost:8067/nexus
    </IfModule>
    </IfModule>
</IfModule>
</IfModule>

When the Apache HTTP Server is restarted you should be able to browse Nexus at http://dev.net:81/nexus.

Important

Nexus needs a different VirtualHost otherwise it will run into the following HTTP 401 Unauthorized error for /nexus/service/local/status?_dc=..., causing the Version unavailable message.

This a result from the browser and Apache passing on the Basic Authorization information from the dev.net Realm to the Plexus webcontainer.

trick13.1.5. Nexus configuration

trick13.1.5.1. Users

Log In with the admin and default password admin123. Select SecurityChange Password to change it. Next select SecurityUsers to change the Email addresses of the admin, anonymous and deployment users to for example nexus.admin@company.org.

Right click on the deployment user and Set Password and Log Out.

trick13.1.5.2. Server Administration

Log In with the admin and the new password. Select AdministrationServer.

Configure the SMTP Settings:

  • Hostname: mail.dev.net.

  • Port: 25.

  • Username: blank.

  • Password: blank.

  • System Email: nexus.noreply@company.org.

Enable Application Server Settings:

  • Base URL: http://dev.net:81/nexus and click Save.

trick13.1.5.3. Repositories

Activate downloading of the remote indexes for the proxy repositories that Nexus ships. Select Views/RepositoriesRepositories and repeat the following step for Central, Apache Snapshots and Codehaus Snapshots:

  • Left click on the repository and switch to the Configuration tab to set Download Remote Indexes: True and click Save.

Select AdministrationScheduled TasksRefresh to check the Status of the Repair Repositories Index task (see also NEXUS-431), that was started automatically. When the task is already finished it is possible to view the information in Views/RepositoriesSystem FeedsSystem changes in Nexus.

When the repository indexing is finished it is possible to use Artifact Search and actually find something.

trick13.1.5.3.1. Reinstate Public Snapshot Repositories

Recreate the separate Public Snapshot Repositories (see also NEXUS-3374) by selecting Views/RepositoriesRepositoriesAdd...Repository Group with:

  • Group ID: public-snapshots.

  • Group Name: Public Snapshot Repositories.

  • Provider: Maven2.

  • Format: maven2.

  • Publish URL: true and click Save.

Select Views/RepositoriesRepositoriesRefreshPublic Snapshot Repositories and on the Configuration tab drag Apache Snapshots and Codehaus Snapshots from the Available Repositories in Ordered Group Repositories and click Save.

For the Public Repositories on the Configuration tab remove Apache Snapshots and Codehaus Snapshots from the Ordered Group Repositories and click Save.

trick13.1.5.3.2. JBoss

Optionally configure the JBoss repository (see also JBBUILD-688) by selecting Views/RepositoriesRepositoriesAdd...Proxy Repository with:

  • Repository ID: jboss.

  • Repository Name: JBoss.

  • Provider: Maven2.

  • Repository Policy: Release.

  • Remote Storage Location: https://repository.jboss.org/nexus/content/repositories/releases/.

  • Download Remote Indexes: True.

  • Checksum Policy: StrictIfExists and click Save.

  • Repository ID: jboss-thirdparty.

  • Repository Name: JBoss 3rd party.

  • Provider: Maven2.

  • Repository Policy: Release.

  • Remote Storage Location: https://repository.jboss.org/nexus/content/repositories/thirdparty-releases/.

  • Download Remote Indexes: True.

  • Checksum Policy: StrictIfExists and click Save.

Select Views/RepositoriesRepositoriesRefreshPublic Repositories and on the Configuration tab drag JBoss from the Available Repositories somewhere below Central in Ordered Group Repositories and click Save.

Then drag JBoss 3rd party from the Available Repositories just below JBoss in Ordered Group Repositories and click Save.

trick13.1.5.3.3. Spring

Optionally configure the SpringSource Enterprise Repositories by selecting Views/RepositoriesRepositoriesAdd...Proxy Repository with:

  • Repository ID: spring-release.

  • Repository Name: SpringSource EBR - SpringSource Bundle Releases.

  • Provider: Maven2.

  • Repository Policy: Release.

  • Remote Storage Location: http://repository.springsource.com/maven/bundles/release/.

  • Download Remote Indexes: True.

  • Checksum Policy: StrictIfExists and click Save.

  • Repository ID: spring-external.

  • Repository Name: SpringSource EBR - External Bundle Releases.

  • Provider: Maven2.

  • Repository Policy: Release.

  • Remote Storage Location: http://repository.springsource.com/maven/bundles/external/.

  • Download Remote Indexes: True.

  • Checksum Policy: StrictIfExists and click Save.

  • Repository ID: spring-milestone.

  • Repository Name: SpringSource EBR – External Bundle Milestones.

  • Provider: Maven2.

  • Repository Policy: Release.

  • Remote Storage Location: http://repository.springsource.com/maven/bundles/milestone/.

  • Download Remote Indexes: True.

  • Checksum Policy: StrictIfExists and click Save.

Select Views/RepositoriesRepositoriesRefreshPublic Repositories and on the Configuration tab drag SpringSource EBR - SpringSource Bundle Releases from the Available Repositories somewhere below Central in Ordered Group Repositories.

Then drag SpringSource EBR - External Bundle Releases from the Available Repositories just below SpringSource EBR - SpringSource Bundle Releases in Ordered Group Repositories.

Finally drag SpringSource EBR – External Bundle Milestones from the Available Repositories just below SpringSource EBR - External Bundle Releases in Ordered Group Repositories and click Save.

trick13.1.5.4. Scheduled tasks

When the below mentioned tasks are configured it is possible to start extra unscheduled runs with AdministrationScheduled Tasks, right clicking on the desired task and selecting Run. Follow the task progress in Views/RepositoriesSystem FeedsSystem changes in NexusRefresh.

trick13.1.5.4.1. Indexing

Configure a task to publish hosted releases index by selecting AdministrationScheduled TasksAdd with:

  • Name: Publish hosted releases index.

  • Task Type: Publish Indexes.

  • Repository/Group: Releases (Repo).

  • Alert Email : nexus.task@company.org.

  • Recurrence: Daily.

  • Start Date: Today.

  • Recurring Time: 22:00 and click Save.

Configure a task to reindex all repositories by selecting AdministrationScheduled TasksAdd with:

  • Name: Reindex all repositories.

  • Task Type: Repair Repositories Index.

  • Repository/Group: All Repositories.

  • Do full reindex: Checked.

  • Alert Email : nexus.task@company.org.

  • Recurrence: Weekly.

  • Start Date: Today.

  • Recurring Time: 00:00.

  • Selected Days: Sunday and click Save.

Configure a task to download all repositories indexes by selecting AdministrationScheduled TasksAdd with:

  • Name: Download all repositories indexes.

  • Task Type: Download Indexes.

  • Repository/Group: All Repositories.

  • Alert Email : nexus.task@company.org.

  • Recurrence: Weekly.

  • Start Date: Today.

  • Recurring Time: 20:00.

  • Selected Days: Monday and click Save.

Configure a task to optimize all repositories indexes by selecting AdministrationScheduled TasksAdd with:

  • Name: Optimize indexes.

  • Task Type: Optimize Repository Index.

  • Repository/Group: All Repositories.

  • Alert Email : nexus.task@company.org.

  • Recurrence: Weekly.

  • Start Date: Today.

  • Recurring Time: 21:00.

  • Selected Days: Tuesday and click Save.

trick13.1.5.4.2. Cleanup

Configure a task to cleanup snapshots by selecting AdministrationScheduled TasksAdd with:

  • Name: Cleanup snapshots.

  • Task Type: Remove Snapshots From Repository.

  • Repository/Group: All Repositories.

  • Minimum snapshot count: 3.

  • Snapshot retention (days): 7.

  • Remove if released: Checked.

  • Delete immediately: Checked.

  • Alert Email : nexus.task@company.org.

  • Recurrence: Daily.

  • Start Date: Today.

  • Recurring Time: 19:00 and click Save.

Configure a task to cleanup interaction information by selecting AdministrationScheduled TasksAdd with:

  • Name: Cleanup interaction information.

  • Task Type: Purge Nexus Timeline.

  • Purge older items than (days) : 30.

  • Alert Email : nexus.task@company.org.

  • Recurrence: Monthly.

  • Start Date: Today.

  • Recurring Time: 23:00.

  • Days: Last and click Save.

Configure a task to cleanup unused items by selecting AdministrationScheduled TasksAdd with:

  • But uncheck Enable for now.

  • Name: Cleanup unused items.

  • Task Type: Evict Unused Proxied Items From Repository Cache.

  • Repository/Group: All Repositories.

  • Evict items older than (days): 360.

  • Alert Email : nexus.task@company.org.

  • Recurrence: Monthly.

  • Start Date: Today.

  • Recurring Time: 08:00.

  • Days: 1 and click Save.

Configure a task to cleanup trash by selecting AdministrationScheduled TasksAdd with:

  • Name: Cleanup trash.

  • Task Type: Empty Trash.

  • Purge items older than (days): 28.

  • Alert Email : nexus.task@company.org.

  • Recurrence: Daily.

  • Start Date: Today.

  • Recurring Time: 22:30 and click Save.

trick13.1.6. Maven integration

trick13.1.6.1. Artifact repository

Configure Maven to use the Nexus Repository with the following mirror settings 1-2 in the Maven configuration file P:\dev\apps\build\apache-maven-3.0.4\conf\settings.xml to correspond with in the Views/RepositoriesRepositories available Repository Path of the Public Snapshot Repositories and the Public Repositories:

  <mirrors>
    <mirror>
      <id>nexus-public-snapshots</id>
      <mirrorOf>public-snapshots.dev.nettrick1</mirrorOf>
      <url>http://dev.net:81/nexus/content/groups/public-snapshots</url>
    </mirror>
    <mirror>
      <id>nexus-central</id>
      <mirrorOf>*trick2</mirrorOf>
      <url>http://dev.net:81/nexus/content/groups/public</url>
    </mirror>
  </mirrors>

Configure Maven to use the Nexus Public Repositories by default (see also * mirrorOf 2) with the following profile 1 and activateProfile settings in the Maven configuration file P:\dev\apps\build\apache-maven-3.0.4\conf\settings.xml:

  <profiles>
    <profile>
      <id>developmenttrick1</id>
      <repositories>
        <repository>
          <id>central.dev.net</id>
          <url>http://dev.net:81/nexus/content/groups/public</url> <!-- (see 2) -->
          <releases>
            <enabled>true</enabled>
          </releases>
          <snapshots>
            <enabled>true</enabled>
            <updatePolicy>always</updatePolicy>
          </snapshots>
        </repository>
      </repositories>
      <pluginRepositories>
        <pluginRepository>
          <id>central.dev.net</id>
          <url>http://dev.net:81/nexus/content/groups/public</url> <!-- (see 2) -->
          <releases>
            <enabled>true</enabled>
          </releases>
          <snapshots>
            <enabled>true</enabled>
            <updatePolicy>always</updatePolicy>
          </snapshots>
        </pluginRepository>
      </pluginRepositories>
    </profile>
  </profiles>

  <activeProfiles>
    <activeProfile>development</activeProfile>
  </activeProfiles>

Important

The repositories defined in the development profile have releases as well as snapshots enabled because the Views/RepositoriesRepositories for the Public Repositories contains the hosted Releases (internal releases), 3rd party and Central as well as the hosted Snapshots (internal snapshots). The updatePolicy is set to always to make sure that from the hosted internal snapshot repository the latest version is used.

Configure Maven to use the Nexus Public Snapshot Repositories by request (see also public-snapshots.dev.net mirrorOf 1) with the following profile settings in the Maven configuration file P:\dev\apps\build\apache-maven-3.0.4\conf\settings.xml:

  <profiles>
    ...

    <profile>
      <id>public-snapshots</id>
      <repositories>
        <repository>
          <id>public-snapshots.dev.net</id>
          <url>http://dev.net:81/nexus/content/groups/public-snapshots</url> <!-- (see 1) -->
          <releases>
            <enabled>false</enabled>
          </releases>
          <snapshots>
            <enabled>true</enabled>
            <updatePolicy>always</updatePolicy>
          </snapshots>
        </repository>
      </repositories>
      <pluginRepositories>
        <pluginRepository>
          <id>public-snapshots.dev.net</id>
          <url>http://dev.net:81/nexus/content/groups/public-snapshots</url> <!-- (see 1) -->
          <releases>
            <enabled>false</enabled>
          </releases>
          <snapshots>
            <enabled>true</enabled>
            <updatePolicy>always</updatePolicy>
          </snapshots>
        </pluginRepository>
      </pluginRepositories>
    </profile>
  </profiles>

Important

The url entry host must match the mirrorof entry otherwise Maven will look in the Nexus public area because of its * mirrorOf setting.

Note

The updatePolicy is set to always but for proxied snapshot repositories the actual version is determined by Artifact Max Age setting (default value of 1440 minutes = 24 hours) of that particular snapshot repository in Nexus.

For an existing pom.xml run from the command line mvn help:active-profiles and mvn -P public-snapshots help:active-profiles to verify these settings.

trick13.1.6.2. Artifact deployment

Configure Maven projects to use the Nexus Repository for deployments with the following distributionManagement repository settings 1-2 in the Maven project pom.xml to correspond with in the Views/RepositoriesRepositories available Repository Path of the hosted Releases and Snapshots repositories:

  <distributionManagement>
    <repository>
      <id>nexus-releases</id> <!-- (see 1) -->
      <name>Internal Releases</name>
      <url>http://dev.net:81/nexus/content/repositories/releases</url>
    </repository>
    <snapshotRepository>
      <id>nexus-snapshots</id> <!-- (see 2) -->
      <name>Internal Snapshots</name>
      <url>http://dev.net:81/nexus/content/repositories/snapshots</url>
    </snapshotRepository>
  </distributionManagement>

Configure Maven to use the Nexus Repository deployment user with the following server settings 1-3 in the Maven configuration file P:\dev\apps\build\apache-maven-3.0.4\conf\settings.xml to correspond with in the SecurityUsers available User ID with Nexus Deployment Role:

  <servers>
    <server>
      <id>nexus-releasestrick1</id>
      <username>deployment</username>
      <password>password</password>
    </server>
    <server>
      <id>nexus-snapshotstrick2</id>
      <username>deployment</username>
      <password>password</password>
    </server>
    <server>
      <id>nexus-thirdpartytrick3</id>
      <username>deployment</username>
      <password>password</password>
    </server>
  </servers>

Note

It is possible to encrypt the password using Section 4.2.4, “Password Encryption”.

Important

In case of partial deployments, with the maven release plugin for instance, the retries will get HTTP 400 errors. Therefore select Views/RepositoriesRepositoriesReleasesConfiguration and change the Deployment Policy to Allow Redeploy.

trick13.1.6.3. Third-party artifacts

As an alternative to adding a missing third-party artifact from the command line with:

mvn deploy:deploy-file -DrepositoryId=nexus-thirdparty (see 3) ^
           -Durl=http://dev.net:81/nexus/content/repositories/thirdparty ^
           -DgeneratePom=true ^
           -DgroupId=... -DartifactId=... -Dversion=... -Dpackaging=... ^
           -Dfile=...

select Views/RepositoriesRepositories3rd party and on the Artifact Upload tab configure the Group, Artifact and Version (GAV) settings for the third-party artifact.

trickChapter 14. Continuous Integration

trick14.1. Jenkins

In a nutshell, Jenkins (formerly known as Hudson) provides an easy-to-use so-called continuous integration system, making it easier for developers to integrate changes to the project, and making it easier for users to obtain a fresh build. The automated, continuous build increases the productivity.

trick14.1.1. Resources

trick14.1.2. Jenkins installation guide

Download the latest archive: jenkins.war [version 1.462].

trickPress Windows Logo+Break keys to open the Windows System Properties. Select Advanced system settingsEnvironment Variables and add a New system variable JENKINS_HOME pointing to P:\dev\data\ci\jenkins. You need to reboot the server for the Path setting to take effect.

Deploy the .war in Tomcat by dropping it into the directory P:\dev\apps\webserver\apache-tomcat-7.0.25\webapps.

Important

Because Log4J and SLF4J are already installed in P:\dev\apps\webserver\apache-tomcat-7.0.25\lib remove log4j-1.2.9.jar and slf4j-api-1.6.1.jar from the jenkins.war. Otherwise the following error will occur: java.lang.NullPointerException at org.jenkinsci.main.modules.sshd.SSHD.init(SSHD.java:133) caused by Error injecting constructor, java.lang.LinkageError: loader constraint violation: when resolving method "org.slf4j.impl.StaticLoggerBinder.getLoggerFactory()Lorg/slf4j/ILoggerFactory;".

Warning

Jenkins looses build data on restart (see also issue JENKINS-12758). A workaround is to click on Reload Configuration from Disk in the Manage Jenkins page. This properly reloads all builds and they are visible again.

trick14.1.2.1. Maven integration

When using Maven with password encryption it will always look for the file settings-security.xml in the fixed location %USERPROFILE%\.m2. Therefore make sure to create a Tomcat Windows user and copy for example C:\Users\jjasper\.m2\settings-security.xml into C:\Users\tomcat\.m2.

Important

This still may not be enough when using for example truezip-maven-plugin which fails with IOException: Unable to create P:\dev\data\ci\jenkins\jobs\...\${project.artifactId}-${project.version}.war\extras trying to copy additional files into a war. To fix this right-click on the directory P:\dev\data\ci\jenkins\jobs and select PropertiesSecurityEdit...Users (COMPUTERNAME\Users) to allow Modify and thus Write and click OK.

trick14.1.3. Apache configuration

Instruct Apache to proxy all URLs whose path portions begin with /jenkins/ using the following P:\dev\apps\httpserver\apache-conf\httpd-vhosts.conf include 1:

<VirtualHost *:80>
    ...

    <IfModule proxy_module>
    <IfModule proxy_http_module>
        ...

        <Proxy *>
            ...
        </Proxy>

        # Jenkins
        Include ../apache-conf/httpd-jenkins.conftrick1
    </IfModule>
    </IfModule>
</VirtualHost>

with the following content in P:\dev\apps\httpserver\apache-conf\httpd-jenkins.conf:

<IfModule proxy_module>
<IfModule proxy_ajp_module>
    <Location /jenkins>
        Include ../apache-conf/httpd-realm.conf
    </Location>

    ProxyPass /jenkins         ajp://localhost:8069/jenkins
    ProxyPassReverse /jenkins  ajp://localhost:8069/jenkins
</IfModule>
</IfModule>

When the Apache HTTP Server is restarted you should be able to browse Jenkins at http://dev.net/jenkins.

trick14.1.4. Jenkins configuration

trick14.1.4.1. System

Select JenkinsManage JenkinsConfigure System or type config in the search box to set:

  • # of executors: 4 (where a good value to start with would be the number of processors on your system).

  • Quiet period: 60.

  • SCM checkout retry count: 5.

  • Enable security and configure Access Control:

  • Add Ant installation:

    • name: ANT_HOME.

    • Disable Install automatically.

    • ANT_HOME: P:\dev\apps\build\apache-ant-1.8.4.

  • Add Maven installation:

    • name: M2_HOME.

    • Disable Install automatically.

    • MAVEN_HOME: P:\dev\apps\build\apache-maven-3.0.4.

  • CVS:

    • cvs executable: P:\dev\apps\vcs\cvsnt-2.5.03.2382\cvs.

      Tip

      CVSNT ignores the login and password information in the file called .cvspass. To checkout from CVS just use cvs -d:local:P:\dev\data\repo\cvs.

  • Subversion:

    • Subversion Workspace Version: 1.6 (svn:externals to file).

  • Jenkins URL:

    • Jenkins URL: http://dev.net/jenkins/.

  • E-mail Notification:

    • SMTP server: mail.dev.net.

    • Default user e-mail suffix: @company.org.

    • System Admin E-mail Address: jenkins.noreply@company.org and click Save.

trick14.1.4.2. Plugins

Select JenkinsManage JenkinsManage Plugins. Switch to the Advanced tab and click Check now to find updates. When done Go back to update center and switch to the Available tab to check (one-at-a-time works best) for example the following plugins (the other project information will be handled with Chapter 17, Quality Assurance):

  • Audit Trail keeps a log of who performed what particular Jenkins operations, such as configuring jobs.

  • All Changes shows all changes which influenced the builds of a project.

  • Change Log History copied to a later build when a build is deleted.

  • Claim shows up as a build badge, so teammates can see who is working on what along with notes.

  • Dashboard View provides a portal-like view for the Jenkins instance.

  • Dependency Graph View of the Jenkins projects using Graphviz. Displays the dependencies between jobs based on versions in the dependencies of the project pom.xml. Thus shows which components currently use this snapshot/HEAD variant of the project. Useful to see which projects will be effected by check-ins and release of a certain project.

  • Locale controls the language of Jenkins.

  • Green Balls changes Jenkins to use green balls instead of blue for successful builds.

  • Git allows use of Git as a build SCM.

  • Sonar integration (see also Section 17.2, “Sonar”).

After successful Install of all selected plugins reload Jenkins at http://dev.net/tomcat/manager/html for the latest version of the plugin to show up in the Installed tab.

Note

To install the plugin when Jenkins is deployed on Tomcat it is also possible to just copy the .hpi file to P:\dev\data\ci\jenkins\plugins.

Select JenkinsManage JenkinsConfigure System or type config in the search box to set:

  • Audit Trail:

    • Log Location: P:\dev\logs\ci\jenkins\audit.log.

    • Log File Size MB: 10.

    • Log File Count: 10.

    Important

    Make sure P:\dev\logs\ci\jenkins exists. View the log at JenkinsManage JenkinsSystem LogAudit Trail.

  • Locale:

    • Default Language: en_US.

    • Check Ignore browser preference and force this language to all users.

  • Dependency Graph Viewer Configuration:

    • Dot Executable Path: P:\dev\apps\editor\graphviz\bin\dot.exe.

  • trickSonar and Add Sonar with Advanced...:

    • Name: dev.net Sonar (see also Section 17.2, “Sonar”).

    • Server URL: http://localhost:8072/sonar.

    • Server Public URL: http://dev.net/sonar.

    • Database URL: jdbc:mysql://localhost:3306/sonar?useUnicode=true&characterEncoding=utf8&rewriteBatchedStatements=true.

    • Database login: sonar-user.

    • Database password: password.

    • Database driver: com.mysql.jdbc.Driver.

    • Trigger Exclusions:

      • Skip if triggered by SCM Changes.

      • Skip if triggered by the build of a dependency and click Save.

trick14.1.4.3. Subversion

Setup Subversion authentication in Jenkins at http://dev.net/jenkins/scm/SubversionSCM/enterCredential:

  • Repository URL: http://dev.net/svn-repo.

  • Username/password authentication:

    • User name: jenkins.

    • Password: password.

    Note

    When creating a new job for the Subversion scm you would otherwise have been presented with a link in Maybe you need to enter credential? to supply them for the specified URL.

trick14.1.4.4. Git

For Git authentication in Jenkins look at _netrc setup in Section 8.1.3.1.1, “netrc”.

trickChapter 15. Integrated Development Environment

trick15.1. Eclipse

Eclipse is an open source community whose projects are focused on building an open development platform comprised of extensible frameworks, tools and runtimes for building, deploying and managing software across the lifecycle.

trick15.1.1. Resources

trick15.1.2. Eclipse installation guide

Download the archive: eclipse-jee-juno-SR1-win32.zip [version 4.2.1].

Extract this .zip file to P:\dev\apps\ide.

Now rename P:\dev\apps\ide\eclipse to P:\dev\apps\ide\eclipse-4.2.1.

trickConfigure the vm settings 1-4 in P:\dev\apps\ide\eclipse-4.2.1\eclipse.ini:

-startup
...
--launcher.library
...
-product
org.eclipse.epp.package.jee.product
--launcher.defaultAction
openFile
--launcher.XXMaxPermSize
256M
-showsplash
org.eclipse.platform
--launcher.XXMaxPermSize
256m
--launcher.defaultAction
openFile
-vmtrick1
P:/dev/apps/prg/java/jdk1.7.0_09/bin/javaw.exetrick2
-vmargs
-Djava.net.preferIPv4Stack=truetrick3
-Dosgi.requiredJavaVersion=1.5
-Dhelp.lucene.tokenizer=standard
-Xms40m128mtrick4
-Xmx512m

Important

JDK 7 brings support for IPv6 on Windows. When you attempt to connect to an IPv4 address then under the covers it will use an IPv4-mapped IPv6 address. This is causing issues with the Eclipse Juno 'Check for Updates' and ' Eclipse Marketplace'. Therefore add -vmargs -Djava.net.preferIPv4Stack=true3

Initialize the Eclipse configuration with P:\dev\apps\ide\eclipse-4.2.1\eclipse -initialize.

Configure the user's area and the default workspace in P:\dev\apps\ide\eclipse-4.2.1\configuration\config.ini:

osgi.instance.area.default=@user.home/workspaceW:/workspace-4.2.1trick1

For ease of use create a shortcut on the Quick Launch Toolbar by dragging eclipse.exe from P:\dev\apps\ide\eclipse-4.2.1 onto it. Click this shortcut to start Eclipse with his now default Workspace at W:\workspace-4.2.1.

trick15.1.3. Eclipse configuration

Set the following Code Style preferences at WindowPreferencesJavaCode Style:

  • Select Clean Up and click Edit for Active profile: Eclipse [built-in] to roll your own Profile name dev.net. Export those Clean Up settings as eclipse.codestyle.cleanup.dev.net-4.2.1.xml.

  • Select Formatter and click Edit for Active profile: Eclipse [built-in] to roll your own Profile name dev.net. Export the Formatter settings as eclipse.codestyle.formatter.dev.net-4.2.1.xml.

  • Select Organize Imports and click New for the company package net.dev.freedumbytes. Export the Organize Import settings as eclipse.dev.net.importorder. And change the number of imports needed for * to 0.

By the way the shortcuts for formatting source and organizing imports are Ctrl+Shift+F and Ctrl+Shift+O.

trick

Tip

To activate formatting and import organizing when the file is saved select WindowPreferencesJavaEditorSave Actions and check Perform the selected actions on save for Format source codeFormat edited lines and Organize imports.

Caution

Do not run the Additional actions because it can be expensive and slow down the workbench and you might want to preview those changes before accepting them (see also Keep your code clean with Eclipse).

To use the same settings for the other editors select WindowPreferences and type filter text indent:

  • Editor for CSS, HTML and XML:

    • Line width 256.

    • Indent using spaces.

    • Indentation size 2.

To disable auto folding at WindowPreferencesJavaEditorFolding and uncheck all elements under Initially fold these elements.

Change code completion in WindowPreferencesJavaEditorContent Assist to Completion overwrites.

Also select WindowPreferencesJavaEditorTyping and uncheck Tab key adjusts the indentation of the current line. Don't forget to Apply the changes.

trick15.1.3.1. Perspectives

Set the following Perspective preferences:

  • Left click on the icon Open Perspective to add the Java shortcut and the Team Synchronizing shortcut.

  • Right click on the icon Java to no longer Show Text.

  • Optionally right click on the icon Java EE to Close it.

Use Ctrl+F8 to cycle through the perspectives.

trick15.1.3.2. Views

Open the view Package Explorer with Alt+Shift+Q, P and left click on the icon local menu to make the following changes:

  • Package PresentationFlat.

  • Filters... and check Libraries from external.

  • Top Level ElementsWorking Sets.

Note

The shortcut for the local menu is Ctrl+F10 when the view is active. This is also the shortcut for the ruler menu in editors.

Cycle through the views to Outline using Ctrl+F7. This view can be kept closed because Ctrl+O shows the outline of the current source when needed. And Ctrl+F3 shows the outline at the current cursor position.

Tip

Instead of clicking through the view Package Explorer just open the resources with Ctrl+Shift+R or the java types with Ctrl+Shift+T. Now in the editor click Alt+Shift+W and select Package Explorer to locate it in that view, should you be interested in the files at the same location.

The view Console can be opened with Alt+Shift+Q, C.

trick15.1.3.3. Editors

Useful general editor shortcuts:

  • Use F12 to jump back to the last active editor from any view and Ctrl+F6 to cycle through the editors.

  • With Alt+Left and Alt+Right it is possible to move through the file history.

  • Goto line with Ctrl+L.

  • Search in files with Incremental Find Ctrl+J and typing the search text. Find next occurrence with Ctrl+K and the prior one with Ctrl+Shift+K.

  • Search in workspace with Ctrl+H. Because the Java shortcut for finding references is easier to use (see also Java editor shortcuts below) Customize... the Search popup by unchecking Java Search and Remote Search (those options will still be available through the Search menu).

    When working in Ctrl+M maximized mode and a search result is selected this resource is also opened in maximized mode. Simply switch back to the search view with Ctrl+F7. Use Delete to remove search results from the tree. Navigate to the prior search result with Ctrl+, and the next search result with Ctrl+..

    Tip

    To exclude unused working sets or projects in the workspace from search results and other views just Close Project or the complete working set in the view Package Explorer.

    Note

    When encountering the following error An internal error occurred during: Items filtering. Class file name must end with .class during search, close Eclipse:

    • Delete <workspace>/.metadata/.plugins/org.eclipse.jdt.core/*.index.

    • Delete <workspace>/.metadata/.plugins/org.eclipse.jdt.core/savedIndexNames.txt.

trickUseful Java editor shortcuts:

  • Goto declaration with F3.

  • Find references in workspace with Ctrl+Shift+G.

  • Find declarations in workspace with Ctrl+G.

  • Popup type hierarchy with Ctrl+T.

  • Change case to lower Ctrl+Shift+Y or upper Ctrl+Shift+X.

Spell checking is supported by Eclipse and when you see a squiggly mark place the cursor on the word and press Ctrl+1 to view the correction proposals.

Tip

Ctrl+Shift+L opens the shortcuts preference page.

trick15.1.4. Plugins installation guide

Install the following plugins.

Note

To revert an installation select HelpAbout EclipseInstallation DetailsInstallation History and move from Current Installation down and click Revert.

trick15.1.4.1. EGit

EGit is an Eclipse Team provider for the Git version control system. Git is a distributed SCM, which means every developer has a full copy of all history of every revision of the code, making queries against the history very fast and versatile.

Install the plugin EGit in Eclipse:

  • Select HelpInstall New Software....

  • Add... the Location http://download.eclipse.org/egit/updates with Name Main P2 Repository and click Ok.

  • Select to Work with: Main P2 Repository - http://download.eclipse.org/egit/updates.

  • Type filter text: git.

  • Select the following components:

    • Eclipse EGit [2.2.0]

    • Eclipse JGit [2.2.0]

    • EGit Mylyn [2.2.0] and click Next twice.

  • Choose I accept the terms of the license agreements after reading them and Finish.

  • To complete the installation restart Eclipse.

trick15.1.4.2. Mylyn

Mylyn is a task-focused interface for Eclipse that reduces information overload and makes multi-tasking easy. It does this by making tasks a first class part of Eclipse, and integrating rich and offline editing for repositories such as Bugzilla, Trac, and JIRA. Once your tasks are integrated, Mylyn monitors your work activity to identify relevant information, and uses this task context to focus the user interface on the task-at-hand. This puts the information you need at your fingertips and improves productivity by reducing searching, scrolling, and navigation. By making task context explicit Mylyn also facilitates multitasking, planning, reusing past efforts, and sharing expertise.

Update the plugin Mylyn in Eclipse:

  • Select HelpInstall New Software....

  • Select to Work with: Mylyn for Eclipse Juno - http://download.eclipse.org/mylyn/releases/juno.

  • Select the following components:

    • Mylyn Task List [3.8.2]

    • Mylyn Task-Focused Interface [3.8.2]

    • Mylyn WikiText [1.7.2]

    • Mylyn Builds Connector: Hudson/Jenkins [1.0.2]

    • Mylyn Context Connector: Eclipse IDE [3.8.2]

    • Mylyn Context Connector: Java Development [3.8.2]

    • Mylyn Context Connector: Plug-in Development [3.8.2]

    • Mylyn Context Connector: Team Support [3.8.2]

    • Mylyn Tasks Connector: Bugzilla [3.8.2]

    • Mylyn Versions Connector: CVS [1.0.2]

    • Mylyn Versions Connector: Subclipse [1.0.2]

    • Mylyn Versions Connector: Git [1.0.2] and click Next twice.

  • Choose I accept the terms of the license agreements after reading them and Finish.

  • To complete the installation restart Eclipse.

For JIRA support:

  • Select HelpInstall New Software....

  • Add... the Location http://update.atlassian.com/atlassian-eclipse-plugin/e3.8 with Name Atlassian Connector for Eclipse and click Ok.

  • Select to Work with: Atlassian Connector for Eclipse - http://update.atlassian.com/atlassian-eclipse-plugin/e3.8.

  • Select the following component:

  • Choose I accept the terms of the license agreements after reading them and Finish.

  • To complete the installation restart Eclipse.

Note

Optionally select WindowPreferencesAtlassian ConnectorUsage Data to uncheck Enable monitoring and automatic submission.

trick15.1.4.3. Subclipse

Subclipse is an Eclipse Team Provider plug-in providing support for Subversion within the Eclipse IDE.

Install the plugin Subclipse in Eclipse:

  • Select HelpInstall New Software....

  • Add... the Location http://subclipse.tigris.org/update_1.8.x with Name Subclipse 1.8.x Update Site and click Ok.

  • Select to Work with: Subclipse 1.8.x Update Site - http://subclipse.tigris.org/update_1.8.x.

  • Select the following components:

    • SVNKit Library [1.7.6]

    • JNA Library [3.4.0]

    • CollabNet Merge Client [3.0.12]

    • Subclipse [1.8.17]

    • Subclipse Integration for Mylyn 3.x [3.0.0]

    • Subversion Client Adapter [1.8.3]

    • Subversion JavaHL Native Library Adapter [1.7.8]

    • Subversion Revision Graph [1.1.1]

    • SVNKit Client Adapter [1.7.8] and click Next twice.

  • Choose I accept the terms of the license agreements after reading them and Finish.

  • To complete the installation restart Eclipse.

Note

Optionally select WindowPreferencesTeamSVNUsage Reporting to uncheck Allow the Subclipse team to receive anonymous usage statistics for this Eclipse installation.

trick15.1.4.4. CVS

Eclipse doesn't support the SSPI CVSNT protocol yet (see also issue 41097). To roll your own patched CVS plug-in jar see Tips & Tricks Section A.2.1, “Patch, test and build an Eclipse plugin”. Move this file org.eclipse.team.cvs.core_3.3.101.r34x_20090115.jar to P:\dev\apps\ide\eclipse\plugins. Close Eclipse before overwriting or renaming the old org.eclipse.team.cvs.core_3.3.101.r34x_....jar to *.old.

Important

This patch is not really neccessary because it is just a convenience method build upon Eclipse Ext Connection Method (see also Section A.2.2.3, “CVS repository”).

trick15.1.4.5. Maven

Maven integration for Eclipse provides tight integration for Maven into the IDE.

Install the plugin M2Eclipse in Eclipse:

  • Select HelpInstall New Software....

  • Add... the Location http://download.eclipse.org/technology/m2e/releases/ with Name m2e releases repository and click Ok.

  • Select to Work with: m2e releases repository - http://download.eclipse.org/technology/m2e/releases/.

  • Type filter text: m2e.

  • Select the following components:

    • m2e - Maven Integration for Eclipse [1.2.0] and click Next twice.

  • Choose I accept the terms of the license agreements after reading them and Finish.

  • To complete the installation restart Eclipse.

Important

If you get the following JDK warning: The Maven Integration requires that Eclipse be running in a JDK, because a number of Maven core plugins are using jars from the JDK. Please make sure the -vm option in eclipse.ini is pointing to a JDK and verify that Installed JREs are also using JDK installs.

Select WindowPreferencesJavaInstalled JREsAdd a Standard VM and Next set the JRE home with Browse to P:\dev\apps\prg\java\jdk1.7.0_09 and click Finish. Now check this jdk1.7.0_09 and Remove the old jre1.x.x_xx and apply with OK (see also Section 15.1.2, “Eclipse installation guide”).

trick15.1.4.6. JD-Eclipse

JD-Eclipse allows you to display all the Java sources during your debugging process, even if you do not have them all.

Install the plugin JDEclipse-Realign in Eclipse:

  • Select HelpInstall New Software....

  • Add... the Location http://mchr3k-eclipse.appspot.com/ with Name JDEclipse-Realign Update Site and click Ok.

  • Select to Work with: JDEclipse-Realign Update Site - http://mchr3k-eclipse.appspot.com/.

  • Select the following components:

    • JD-Eclipse Plug-in [0.1.3].

    • JD Eclipse (Realign Edition) [1.1.2] and click Next twice.

      Realignment fragment for JD-Eclipse host plug-in. This plug-in for Eclipse makes the decompiled code line numbers actually match to the line numbers from the java-class file. As a result, it is possible to debug without source code.

  • Choose I accept the terms of the license agreements after reading them and Finish.

  • To complete the installation restart Eclipse.

trick15.1.5. Plugins configuration

Next configure those plugins.

trick15.1.5.1. Git

Set the following preferences at WindowPreferences:

  • Select TeamGitLabel Decorations:

    • Text Decorations: clear Files, Folders and Projects.

    • Icon Decorations: check Tracked resources, Staged resources, Assumed unchanged resources, Untracked resources, Conflicting resources, Dirty resources and click Apply.

  • Select TeamGit and as Default Repository folder enter W:\projects and click OK.

trick15.1.5.2. Subversion

Set the following preferences at WindowPreferences:

  • Select TeamSVNLabel Decorations:

    • Text: clear File Format, Folder Format and Project Format.

    • Icons: check Indicate is outgoing, Indicate has remote, Indicate is added, Indicate is new resouce, Indicate is external resource and click Apply.

  • Select TeamSVN and as SVN Interface Client choose SVNKit (Pure Java) and click OK.

trick15.1.5.3. CVS

Set the following preferences at WindowPreferences:

  • Select TeamCVSLabel Decorations:

    • Text Decorations: blank File Decoration, Folder Decoration and Project Decoration.

    • Icon Decorations: check Outgoing changes, Remote resources, Added resources, New resources and click Apply.

  • Select TeamCVSExt Connection Method and Use an external program to connect as follows:

    • CVS_RSH: P:\dev\apps\vcs\cvsnt-2.5.03.2382\extnt.exe.

    • Parameters: {host} -l {user} -P {password}.

    • CVS_SERVER: cvsnt and click OK.

trick15.1.5.4. Mylyn

Set the following WindowPreferences:

  • In MylynTeam define Commit Comment Template:

    ${connector.task.prefix} ${task.key}: ${task.description} 
    ${task.url}

    and click Apply.

In Java perspective activate the Mylyn views with WindowShow ViewOther... or shortcut Alt+Shift+Q, Q and from Mylyn select: Task List, Task Repositories and Builds.

Open the Task List view with Alt+Shift+Q, K (see also the User Guide for shortcuts and a UI Legend, which is also available in the local menu Show UI Legend).

trick15.1.5.4.1. JIRA integration

In the Task Repositories view open the local menu with Ctrl+F10 to Add Task Repository.... Select JIRA and click Next:

  • Server: http://dev.net/jira.

  • Label: dev.net jira.

  • User ID: jjasper.

  • Password: password.

  • Open Additional Settings:

    • Subtasks: Show linked tasks.

    • Advanced Configuration:

      • Date Picker Format: yyyy-MM-dd.

      • Date Time Picker Format: yyyy-MM-dd HH:mm.

  • Open Http Authentication and check Enable Http Authentication:

    • User ID: jjasper.

    • Password: password.

  • Open Task Editor Settings: Confluence (default).

  • Validate Settings and click Finish and do not create a query yet.

Add queries to the dev.net jira task repository by right clicking on it and selecting New Query.... Select Create query using form and click Next:

  • Query Title: dev.net issues.

  • Assigned To: Current User and click Finish.

Repeat steps to create the query:

  • Query Title: dev.net interests.

  • Reported By: Current User and click Finish.

Note

The other issues, that are viewed in Eclipse, will show up in the category Uncategorized.

trick15.1.5.4.2. Bugzilla integration

In the Task Repositories view open the local menu with Ctrl+F10 to Add Task Repository.... Select Bugzilla and click Next:

  • Server: http://dev.net/bugzilla.

  • Label: dev.net bugzilla.

  • Uncheck Anonymous.

  • User ID: jjasper.

  • Password: password.

  • Open Additional Settings:

    • Check Local users enabled (see also settings of Emailregexpdesc in Section B.2.1.4.1, “Parameters”).

    • Uncheck Autodetect platform and os.

      Note

      If it is disabled try this again after first saving the other settings.

  • Open Http Authentication and check Enable Http Authentication:

    • User ID: jjasper.

    • Password: password.

  • Open Task Editor Settings: Textile (default).

  • Validate Settings and click Finish and do not create a query yet.

Add queries to the dev.net bugzilla task repository by right clicking on it and selecting New Query.... Select Create query using form and click Next:

  • Query Title: dev.net Bugzilla issues.

  • Email: jjasper who is the Owner and click Finish.

Repeat steps to create the query:

  • Query Title: dev.net Bugzilla interests.

  • Email: jjasper who is the Reporter, CC, and/or QA Contact and click Finish.

The other issues, that are viewed in Eclipse, will show up in the category Uncategorized.

Note

Mylyn periodically checks config.cgi to retrieve the repository configuration. If this results in heavy CPU Load for the regeneration and a big surge in band width use. Take a look at the following Tips for server administrators.

trick15.1.5.4.3. Jenkins integration

In the Builds view select Add Build Server.... Select Hudson (supports Jenkins) and click Next:

  • Server: http://dev.net/jenkins.

  • Label: dev.net builds.

  • Keep: Anonymous checked.

  • Open Http Authentication and check Enable Http Authentication:

    • User ID: jjasper.

    • Password: password.

  • Validate and click Refresh.

  • Click Select All in Build Plans and click Finish.

Set the following WindowPreferences:

  • In MylynBuilds check Automatically refresh builds and click Apply.

trick15.1.5.5. Maven

Set the following preferences WindowPreferences:

  • In TeamIgnored ResourcesAdd Pattern... for target, .settings, .classpath and .project and click Apply.

    Note

    As an alternative see also Section 11.1.2.5, “Ignores template” for Git and Section B.1.1.6, “Global ignores” for Subversion.

  • In MavenInstallations:

    • Add... the latest Maven installation directory: P:\dev\apps\build\apache-maven-3.0.4 and click OK. Check this new Maven installation and click Apply.

  • In Maven:

    • Check Download Artifact Sources.

    • Check Download Artifact JavaDoc.

    • Check Download repository index updates on startup and click Apply.

    Important

    Using the option Hide folders of physically nested modules (experimental) can lead to merge conflicts messages in Team Synchronizing.

    Tip

    As an alternative right-click on the submodule and select Properties or Alt+Enter to set the attribute Derived. By the way the M2E plugin should set the derived flag on modules folders as well as on output folders, such as target/classes, on project import. But there seems to be a bug because the flag ain't set for the module folders.

    Note

    When running mvn clean the derived flag is reset on the target folder. Instead of setting it for every single target folder, right-click on the Working Set, select MavenUpdate Project Configuration... and click Ok.

  • In MavenUser Interface:

    • Optionally check Open XML page in the POM editor by default and click OK.

Optionally in Java perspective activate the Maven view with WindowShow ViewOther... or shortcut Alt+Shift+Q, Q and from Maven select: Maven Repositories. Optionally drag the view Maven Repositories next to the view Package Explorer.

trick15.1.5.5.1. Maven workspace integration approach

Maven/Eclipse workspace integration approach implemented in M2Eclipse 0.12 and earlier was to execute some parts of Maven build lifecycle inside and then configure Eclipse workspace project based on after-execution state collected in Maven Project instance. To solve long-standing issues, M2E 1.0 requires explicit instructions what to do with all Maven plugins bound to interesting phases (see M2E interesting lifecycle phases) of project build lifecycle.

Thus in case of errors like Plugin execution not covered by lifecycle configuration: groupId 1 : artifactId 2 : version 3 : goal 4 (execution: ..., phase: ...) switch to the Problems View and right-click on the error to try a Quick Fix or Ctrl+1 the first basic action Permanently mark goal 1 in pom.xml as ignored in Eclipse build. Resulting in the following pom.xml entry:

  <build>
    <pluginManagement>
      <plugins>
        ...

        <!--This plugin's configuration is used to store Eclipse m2e settings only. It has no influence on the Maven build itself.-->
        <plugin>
          <groupId>org.eclipse.m2e</groupId>
          <artifactId>lifecycle-mapping</artifactId>
          <version>1.0.0</version>
          <configuration>
            <lifecycleMappingMetadata>
              <pluginExecutions>
                <pluginExecution>
                  <pluginExecutionFilter>
                    <groupId>trick1</groupId>
                    <artifactId>trick2</artifactId>
                    <versionRange>trick3</versionRange>
                    <goals>
                      <goal>trick4</goal>
                    </goals>
                  </pluginExecutionFilter>
                  <action>
                    <ignore/>
                  </action>
                </pluginExecution>
              </pluginExecutions>
            </lifecycleMappingMetadata>
          </configuration>
        </plugin>
      </plugins>
    </pluginManagement>
   </build>

With this fix in place run project configuration update with a right-click on the Working Set, select MavenUpdate Project Configuration... and click Ok. Alternatively in the Problems View apply a Quick Fix for Project configuration is not up-to-date with pom.xml. Run project configuration update.

trick15.1.6. Team support

trick15.1.6.1. Mylyn tasks

It is possible to filter completed tasks with Hide Completed Tasks.

Important

When you didn't save passwords in the Repository Settings you will see the warning icon synchronization failed in front of the related queries. In that case just double click on the repository name in the Task Repositories view, reenter the required passwords, Validate Settings and click Finish. After that it should be possible to Synchronize with the repository in the Task List view.

To change the default Task List backup location select WindowPreferencesMylynTasksAdvanced. Restore a backup by selecting one from FileImport...TasksTask List and Contexts.

New tasks/issues can now be created in Eclipse by clicking New Task, New Subtask or Alt+Shift+N, T (or creating one directly from events in the Error Log view with Report as Bug):

  • Selecting the appropriate repository and click Next.

  • Select the product after Update Projects from Repository when it isn't already there and click Finish.

  • After entering the issue click Submit.

Tip

If you get the following error: Unable to submit at this time. Check connectivity and retry. when the connection is valid, try to reproduce the error using the Open with Web Browser option. For example when running Bugzilla without an SMTP server configured this causes the above mentioned error. In the Web Browser you will see the following error: There was an error sending mail from 'bugzilla.noreply@company.org' to 'test-user@company.org':Couldn't connect to localhost. In this case make sure that all users have Bugmail Disabled (see also Section B.2.1.4.3, “Users”).

If you notice that the changes did make it in the issue tracker open the Task again. Click Synchronize Incoming Changes to fetch them and then delete the now obsolete local changes with Clear outgoing.

The following shortcuts are available for tasks:

  • Ctrl+F12: Open task dialog.

  • Ctrl+Shift+F12: Open repository task dialog to find tasks not available on the Task List view. Then drag and drop this Issue or Bug onto the Task List if necessary.

  • Ctrl+F9: Activate task dialog.

  • Ctrl+Shift+F9: Deactivate current task.

Important

It is possible to hyperlink other task in comments but for these hyperlinks to be useful also for the issue trackers themselves use only the following formats:

  • Bugzilla: bug 1 or bug #2.

  • JIRA: the project key followed by issue number, for example: JMW-1.

These same entries can be used in comments in java and resource files. To activate hyperlinking in those files associate the appropriate Task Repository by right clicking on the project and open PropertiesTask Repository and selecting the appropriate one.

trick15.1.6.2. Mylyn task focus

When you first activate a task you will notice that the Package Explorer view is empty in Focus on Active Task mode. It is possible to drill down from the Working Set or any other node to the interesting bits using Alt+click or the plus icon displayed behind the node to Show Filtered Children. Use Ctrl+click to select multiple interesting nodes. When finished marking interesting nodes click (without Ctrl) on whitespace or an already marked node to filter the uninteresting nodes again. Type Ctrl+Alt+Shift+Up to Mark as Landmark an element in the resource tree. Type Ctrl+Alt+Shift+Down to Remove from Context the selected node.

Note

Closing a file will make its node uninteresting immediately (see also WindowPreferencesMylynContextRemove file from context when editor is closed).

Tip

Once the task is finished attach the current context to it. This way it is possible to restore the last context should the task (re)enter someone's Task List. Just right click on the task and select Context Retrieve... to do so.

trick15.1.6.3. Bugfixing

Should the code require bugfixing and a resource needs to be changed in the bugfix as well as a new feature being worked on one might consider to create a patch for the new feature and revert the current changes.

Open the Team Synchronizing perspective and in the Synchronize view right click on the Change Set for the conflicting new feature. Select Create Patch... to open the Changes pane in the Show Change Sets mode. Select the Save to clipboard setting and click Finish.

Right click on the Change Set for the conflicting new feature again and select Open Corresponding Task. Open the Attachments, click Attach..., with Clipboard setting and click Next. Check Patch and enter a Description of backup patch and click Finish (or Next to verify what you are going to save first).

Finally right click on the Change Set for the conflicting new feature to Override and Update all the changed resources.

Once the bugfix is commited reactive the new feature with Ctrl+F9 in the activate task dialog and go to the task itself with Ctrl+F12. Open the Attachments, select the attachment with your Description of backup patch by double clicking on it. The patch will be opened in the Eclipse Web Browser. First type Shift+F10 and Select All then type Shift+F10 again and select Copy. Now in the Package Explorer view right click on a project node and select TeamApply Patch... from the Clipboard with NextFinish. In case of conflicts you might need to play with or Guess the Maximum fuzz factor and Generate a .rej file for unmerged hunks next to the problem resource to manually apply some of the changes.

Important

Make sure that formatting changes aren't a big part of the patch (see also Tip on Eclipse Save Actions).

trickChapter 16. Project

Lets setup a base structure, for Maven projects to come, with the following JIRA project:

  • Maven Setup [MVNSTP]: Maven support components. (for the source see Appendix D, Source)

    With the following components:

    1. setup: Setup the site, license and plugin configuration files.

    2. base-pom: Java Project Object Model: dependencies, build and reporting settings.

    and versions:

    • 2.0 - Base structure for Maven projects to come.

    • 2.1 - Quality Assurance.

trick16.1. Setup base components

Start a new Git repository maven-setup by calling http://dev.net/git-repo?pn=maven-setup&pd=Maven+support+components&a=create direct or through the GitWeb user interface.

Clone this remote repository with the following command git-clone jjasper maven-setup.

Create the minimal POM in W:\projects\maven-setup\pom.xml:

+<?xml version="1.0" encoding="UTF-8"?>
+
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
+                             http://maven.apache.org/maven-v4_0_0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <groupId>net.dev.freedumbytes.maven</groupId>
+  <artifactId>setup</artifactId>
+  <version>2.0-SNAPSHOT</version>
+  <packaging>pom</packaging>
+</project>

In Eclipse create a Working Set Maven Setup and import this Maven Setup project into it with FileImport...MavenExisting Maven Projects from Root directory W:\projects\maven-setup and click Finish.

Tip

To exclude the target directory from search actions and the like, right click on it and select PropertiesDerived.

trick16.1.1. Team Synchronizing Git

Right-click on the Working Set MVNSTP and select TeamShare Project...GitNextUse or create Repository in parent folder of project and click Finish.

Open the Team Synchronizing perspective and select Synchronize...Git and click Next to synchronize with the Destination refs/heads/master for the maven-setup [master] and Include local uncommited changes in comparison and click Finish.

Other available options are Pull and Push.

trick16.1.2. Project information

Supply the project information in W:\projects\maven-setup\pom.xml:

   <artifactId>setup</artifactId>
   <version>2.0-SNAPSHOT</version>
   <packaging>pom</packaging>
+
+  <name>Free Dumb Bytes Maven Setup</name>
+  <description>Setup the site, license and plugin configuration files.</description>
+  <url>http://dev.net/mvn-sites/maven-setup</url>
+  <inceptionYear>2010</inceptionYear>
+  <licenses>
+    <license>
+      <name>GNU Lesser General Public License</name>
+      <url>http://www.gnu.org/licenses/lgpl.html</url>
+      <distribution>repo</distribution>
+    </license>
+  </licenses>
+  <organization>
+    <name>Free Dumb Bytes</name>
+    <url>http://dev.net</url>
+  </organization>
+  <developers>
+    <developer>
+      <id>jjasper</id>
+      <name>Jene Jasper</name>
+      <email>jjasper@dev.java.net</email>
+      <organization>Free Dumb Bytes</organization>
+      <organizationUrl>http://dev.net</organizationUrl>
+      <roles>
+        <role>developer</role>
+      </roles>
+      <timezone>+1</timezone>
+    </developer>
+  </developers>
+
+  <contributors />
 </project>

Note

All patch snippets are split into logical blocks and non essential lines are removed for better page breaks in the generated pdf and the html print out.

trick16.1.3. Environment

Define the Continuous Integration build system, the Issue Tracker system and the Version Control System management in W:\projects\maven-setup\pom.xml:

   </developers>
 
   <contributors />
+
+  <ciManagement>
+    <system>Jenkins</system>
+    <url>http://dev.net/jenkins</url>
+  </ciManagement>
+  <issueManagement>
+    <system>JIRA</system>
+    <url>http://dev.net/jira</url>
+  </issueManagement>
+  <mailingLists />
+  <scm>
+    <developerConnection>scm:git:http://dev.net/git-repo/maven-setup.git</developerConnection>
+    <url>http://dev.net/fisheye/browse/maven-setup</url>
+  </scm>
 </project>

trick16.1.4. Site

The Site Plugin is used to generate a site for the project. The generated site also includes the project's reports that were configured in the <reporting/> section of the POM.

trick16.1.4.1. Configuration

Setup the initial site descriptor in W:\projects\maven-setup\src\site\site.xml:

+<?xml version="1.0" encoding="UTF-8"?>
+
+<project xmlns="http://maven.apache.org/DECORATION/1.1.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/DECORATION/1.1.0
+                             http://maven.apache.org/xsd/decoration-1.1.0.xsd">
+  <bannerLeft>
+    <name>Free Dumb Bytes</name>
+    <href>http://dev.net</href>
+  </bannerLeft>
+
+  <publishDate position="left" format="yyyy-MM-dd HH:mm:ss z" />
+  <version position="left" />
+  <body>
+    <menu name="Free Dumb Bytes" inherit="top">
+      <item name="Maven" href="http://dev.net/mvn-sites" />
+      <item name="FishEye" href="http://dev.net/fisheye/browse" />
+      <item name="JIRA" href="http://dev.net/jira" />
+      <item name="Nexus" href="http://dev.net:81/nexus" />
+      <item name="Jenkins" href="http://dev.net/jenkins" />
+      <item name="HTTP Server" href="http://dev.net/manual" />
+      <item name="Tomcat" href="http://dev.net/tomcat" />
+      <item name="GlassFish" href="http://dev.net:4848" />
+      <item name="Development Production Line"
+            href="http://jmodalwindow.java.net/manual/dpl/html/index.html" />
+    </menu>
+    <menu inherit="bottom" ref="parent" />
+    <menu inherit="bottom" ref="modules" />
+    <menu inherit="bottom" ref="reports" />
+  </body>
+</project>

Setup the Project Info Reports in W:\projects\maven-setup\pom.xml:

   </scm>
+
+  <reporting>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-project-info-reports-plugin</artifactId>
+        <configuration>
+          <dependencyDetailsEnabled>false</dependencyDetailsEnabled>
+          <dependencyLocationsEnabled>false</dependencyLocationsEnabled>
+          <linkOnly>true</linkOnly>
+        </configuration>
+        <reportSets>
+          <reportSet>
+            <reports>
+              <report>index</report>
+              <report>license</report>
+              <report>project-team</report>
+              <report>cim</report>
+              <report>issue-tracking</report>
+              <report>mailing-list</report>
+              <report>scm</report>
+              <report>dependencies</report>
+              <report>dependency-convergence</report>
+              <report>dependency-management</report>
+              <report>distribution-management</report>
+              <report>plugin-management</report>
+              <report>plugins</report>
+              <report>summary</report>
+              <report>modules</report>
+            </reports>
+          </reportSet>
+        </reportSets>
+      </plugin>
+    </plugins>
+  </reporting>
 </project>

Important

When using Nexus disable the generation of the repository locations in the maven-project-info-reports-plugin <configuration/> of the <reporting/> section with <dependencyLocationEnabled/> set to false (see also issue MPIR-137). This is also a performance boost.

Verify those settings with mvn site in your browser at file:///W:/projects/maven-setup/target/site/index.html.

trick16.1.4.2. Apache Maven Fluido Skin

The Apache Maven Fluido Skin is an Apache Maven site skin built on top of Twitter's Bootstrap.

To switch from the Maven Default Skin to the Apache Maven Fluido Skin edit W:\projects\maven-setup\src\site\site.xml:

   <publishDate position="left" format="yyyy-MM-dd HH:mm:ss z" />
   <version position="left" />
 
+  <skin>
+    <groupId>${skinGroupId}</groupId>
+    <artifactId>${skinArtifactId}</artifactId>
+    <version>${skinVersion}</version>
+  </skin>
+
+  <custom>
+    <fluidoSkin>
+      <topBarEnabled>true</topBarEnabled>
+      <sideBarEnabled>true</sideBarEnabled>
+    </fluidoSkin>
+    <sourceLineNumbersEnabled>true</sourceLineNumbersEnabled>
+  </custom>
+
   <body>
     <menu name="Free Dumb Bytes" inherit="top">
       <item name="Maven" href="http://dev.net/mvn-sites" />

Supply the skin settings in W:\projects\maven-setup\pom.xml:

   </scm>
+
+  <properties>
+    <skinGroupId>org.apache.maven.skins</skinGroupId>
+    <skinArtifactId>maven-fluido-skin</skinArtifactId>
+    <skinVersion>1.2.1</skinVersion>
+  </properties>

   <reporting>

trick16.1.4.3. Project page

Next create a more html like project page instead of the default displayed plain text project <description/> from the pom.xml in W:\projects\maven-setup\src\site\apt\index.apt:

+ -----
+ Index
+ -----
+ Jene Jasper
+ ------
+ 2010-02-23
+ ------
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
+Free Dumb Bytes Maven Setup
+
+ Setup the site, license and plugin configuration files
+ (such as the required version of the basic plugins
+ and the generated site reports).
+* Project Information
+
+ This POM defines the following default information:
+
+ * organization
+
+ * developers
+
+ * contributors
+
+ * ciManagement
+
+ * issueManagement
+
+ []
+ Projects that extend from this POM must at least override the following settings:
+
+ * name
+
+ * description
+
+ * url
+
+ * inceptionYear
+
+ * optionally developers and contributors
+
+ * scm
+
+ []

Note

Maven uses Doxia for its content generation framework. It supports several markup formats: APT (Almost Plain Text), Confluence, Simplified DocBook, FML (FAQ Markup Language), FO, iText, LaTeX, RTF, TWiki, XDoc (popular in Apache land) and XHTML.

trick16.1.5. Plugin Versions

After running mvn site check the Plugin Management, Build Plugins and Report Plugins reports in your browser at file:///W:/projects/maven-setup/target/site/plugin-management.html and file:///W:/projects/maven-setup/target/site/plugins.html to find out about the plugins that get invoked by default. Thus the first batch of plugins that will require a version are:

   </properties>
 
+   <build>
+     <pluginManagement>
+       <plugins>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-clean-plugin</artifactId>
+          <version>2.4.1</version>
+        </plugin>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-plugin-plugin</artifactId>
+          <version>2.9</version>
+        </plugin>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-dependency-plugin</artifactId>
+          <version>2.4</version>
+        </plugin>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-resources-plugin</artifactId>
+          <version>2.5</version>
+          <configuration>
+            <encoding>UTF-8</encoding>
+          </configuration>
+        </plugin>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-antrun-plugin</artifactId>
+          <version>1.7</version>
+        </plugin>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-compiler-plugin</artifactId>
+          <version>2.3.2</version>
+          <configuration>
+            <encoding>UTF-8</encoding>
+          </configuration>
+        </plugin>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-surefire-plugin</artifactId>
+          <version>2.12</version>
+        </plugin>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-jar-plugin</artifactId>
+          <version>2.4</version>
+        </plugin>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-ejb-plugin</artifactId>
+          <version>2.3</version>
+        </plugin>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-war-plugin</artifactId>
+          <version>2.2</version>
+        </plugin>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-rar-plugin</artifactId>
+          <version>2.2</version>
+        </plugin>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-ear-plugin</artifactId>
+          <version>2.7</version>
+        </plugin>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-source-plugin</artifactId>
+          <version>2.1.2</version>
+        </plugin>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-javadoc-plugin</artifactId>
+          <version>2.8.1</version>
+          <configuration>
+            <encoding>UTF-8</encoding>
+            <docencoding>UTF-8</docencoding>
+          </configuration>
+        </plugin>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-assembly-plugin</artifactId>
+          <version>2.3</version>
+        </plugin>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-install-plugin</artifactId>
+          <version>2.3.1</version>
+          <configuration>
+            <createChecksum>true</createChecksum>
+            <updateReleaseInfo>false</updateReleaseInfo>
+          </configuration>
+        </plugin>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-deploy-plugin</artifactId>
+          <version>2.7</version>
+          <configuration>
+            <updateReleaseInfo>true</updateReleaseInfo>
+          </configuration>
+        </plugin>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-release-plugin</artifactId>
+          <version>2.2.2</version>
+          <configuration>
+            <autoVersionSubmodules>true</autoVersionSubmodules>
+          </configuration>
+        </plugin>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-scm-plugin</artifactId>
+          <version>1.7</version>
+        </plugin>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-site-plugin</artifactId>
+          <version>3.0</version>
+          <configuration>
+            <inputEncoding>UTF-8</inputEncoding>
+            <outputEncoding>UTF-8</outputEncoding>
+          </configuration>
+        </plugin>
+      </plugins>
+    </pluginManagement>
+  </build>
   <reporting>
     <plugins>
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-project-info-reports-plugin</artifactId>
+        <version>2.4</version>
         <configuration>
           <dependencyDetailsEnabled>false</dependencyDetailsEnabled>
           <dependencyLocationsEnabled>false</dependencyLocationsEnabled>
         </configuration>

trick16.1.5.1. Encoding

To suppress the following warning [WARNING] Using platform encoding (Cp1252 actually) to copy filtered resources, i.e. build is platform dependent! set the encoding parameters of the plugins that support it to UTF-8, that is a variable-length character encoding for Unicode, or ISO-8859-1 (informally referred to as Latin-1).

To set the same encoding in Eclipse select WindowPreferences and type filter text encoding:

  • General:

    • Content TypesText set Default encoding to UTF-8 and Update the following:

      • Java Properties File.

      • JSP.

      • JSP Fragment.

      • JSP Tag Definition.

    • WorkspaceText file encodingOtherUTF-8

  • Web apply Encoding ISO 10646/Unicode(UTF-8) for the following:

    • CSS Files.

    • HTML Files.

    • JSP Files.

  • XMLXML FilesEncodingISO 10646/Unicode(UTF-8).

trick16.1.6. Deployment

Configure the deployment of the project site on the Apache HTTP Server and the artifacts in the Nexus Repository.

trick16.1.6.1. Site

Enable WebDAV on the Apache HTTP Server (see Section 7.1.12, “Module mod_dav configuration”) for uploading of the Maven sites content and amend the setup W:\projects\maven-setup\pom.xml:

   </scm>
 
+  <distributionManagement>
+    <site>
+      <id>mvn-sitestrick1</id>
+      <name>Maven Documentation Sites</name>
+      <url>dav:http://dev.net/mvn-sites/maven-setup</url>
+    </site>
+  </distributionManagement>
+
   <properties>
   <build>
+    <extensions>
+      <extension>
+        <groupId>org.apache.maven.wagon</groupId>
+         <artifactId>wagon-webdav-jackrabbit</artifactId>
+         <version>2.0</version>
+      </extension>
+    </extensions>
+    
     <pluginManagement>
           <artifactId>maven-site-plugin</artifactId>
           <version>3.0</version>
           <configuration>
+            <generateSitemap>true</generateSitemap>
             <inputEncoding>UTF-8</inputEncoding>
             <outputEncoding>UTF-8</outputEncoding>
           </configuration>

and make note of this in W:\projects\maven-setup\src\site\apt\index.apt:

  * optionally developers and contributors
 
  * scm
+
+ * distributionManagement of the site

Encrypt the Jenkins user password 1 with mvn --encrypt-password password and place it in the Maven configuration file P:\dev\apps\build\apache-maven-3.0.4\conf\settings.xml:

  <servers>
    ...
    <server>
      <id>mvn-sites</id>
      <username>jenkins</username>
      <password>{encrypted password}trick1</password>
    </server>
  </servers>

Verify those settings with mvn site-deploy in your browser at http://dev.net/mvn-sites/maven-setup/index.html.

trick16.1.6.2. Artifact

Configure Nexus as the default artifact repository for the artifact deployment with the following <distributionManagement/> settings in the W:\projects\maven-setup\pom.xml:

   <distributionManagement>
+    <repository>
+      <id>nexus-releases</id>
+      <name>Internal Releases</name>
+      <url>http://dev.net:81/nexus/content/repositories/releases</url>
+    </repository>
+    <snapshotRepository>
+      <id>nexus-snapshots</id>
+      <name>Internal Snapshots</name>
+      <url>http://dev.net:81/nexus/content/repositories/snapshots</url>
+    </snapshotRepository>
     <site>
       <id>mvn-sites</id>

Note

Those repositories are defined in the development profile settings.

and amend the W:\projects\maven-setup\src\site\apt\index.apt:

  * ciManagement
 
  * issueManagement
+
+ * distributionManagement of the releases and snapshots
+
+ <<Note>>: All supported Maven repositories are configured in 
+ {{{http://dev.net:81/nexus/index.html#view-repositories}Nexus}}.

Verify those settings with mvn deploy in your browser at http://dev.net:81/nexus/index.html#nexus-search;gav~net.dev.freedumbytes.maven~setup~~~.

trick16.1.6.3. Navigation tree reuse

To be able to reuse the project setup site descriptor W:\projects\maven-setup\src\site\site.xml attach it as an artifact along with the pom.xml:

   <build>
     <pluginManagement>
       <plugins>
         ...

+        <plugin>
+          <groupId>org.codehaus.mojo</groupId>
+          <artifactId>build-helper-maven-plugin</artifactId>
+          <version>1.7</version>
+        </plugin>
       </plugins>
     </pluginManagement>
+
+    <plugins>
+      <plugin>
+        <groupId>org.codehaus.mojo</groupId>
+        <artifactId>build-helper-maven-plugin</artifactId>
+        <inherited>false</inherited>
+        <executions>
+          <execution>
+            <id>site-descriptor-reuse</id>
+            <phase>package</phase>
+            <goals>
+              <goal>attach-artifact</goal>
+            </goals>
+            <configuration>
+              <artifacts>
+                <artifact>
+                  <file>src/site/site.xml</file>
+                  <classifier>site</classifier>
+                  <type>xml</type>
+                </artifact>
+              </artifacts>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
+    </plugins>
   </build>

Verify those settings with mvn deploy in your browser at http://dev.net:81/nexus/index.html#nexus-search;gav~net.dev.freedumbytes.maven~setup~~~site.

trick16.1.7. Java base POM

Configure the default Java projects settings in a base-pom.

trick16.1.7.1. Compiler

The Compiler Plugin is used to compile the sources of your project. The default compiler is javac and is used to compile Java sources. To compile the sources using the latest JDK of all available java compilers in the Maven settings reference ${jdk.1.7.javac}.

Define a new module base-pom in W:\projects\maven-setup\pom.xml:

</distributionManagement>

+  <modules>
+    <module>base-pom</module>
+  </modules>

Supply the new module W:\projects\maven-setup\base-pom\pom.xml:

+<?xml version="1.0" encoding="UTF-8"?>
+
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
+                             http://maven.apache.org/maven-v4_0_0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <parent>
+    <groupId>net.dev.freedumbytes.maven</groupId>
+    <artifactId>setup</artifactId>
+    <version>2.0-SNAPSHOT</version>
+  </parent>
+  <artifactId>base-pom</artifactId>
+  <packaging>pom</packaging>
+
+  <name>Free Dumb Bytes Base POM</name>
+  <description>Java Project Object Model: dependencies, build and reporting settings.</description>
+  <inceptionYear>2010</inceptionYear>
+  <developers>
+    <developer>
+      <id>jjasper</id>
+      <name>Jene Jasper</name>
+      <email>jjasper@dev.java.net</email>
+      <organization>Free Dumb Bytes</organization>
+      <organizationUrl>http://dev.net</organizationUrl>
+      <roles>
+        <role>developer</role>
+      </roles>
+      <timezone>+1</timezone>
+    </developer>
+  </developers>
+
+  <contributors />
+  <properties>
+    <baseJdkVersion>1.7</baseJdkVersion>
+    <baseJavadocVersion>1.7</baseJavadocVersion>
+    <baseJavacExecutable>${jdk.1.7.javac}</baseJavacExecutable>
+    <baseJavaExecutable>${jdk.1.7.jvm}</baseJavaExecutable>
+    <baseJavadocExecutable>${jdk.1.7.javadoc}</baseJavadocExecutable>
+  </properties>

Note

Those executables are defined in the compiler profile settings.

+  <build>
+    <pluginManagement>
+      <plugins>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-compiler-plugin</artifactId>
+          <configuration>
+            <fork>true</fork>
+            <executable>${baseJavacExecutable}</executable>
+            <compilerVersion>${baseJdkVersion}</compilerVersion>
+            <source>${baseJdkVersion}</source>
+            <target>${baseJdkVersion}</target>
+            <showDeprecation>true</showDeprecation>
+            <showWarnings>true</showWarnings>
+            <meminitial>128m</meminitial>
+            <maxmem>512m</maxmem>
+          </configuration>
+        </plugin>
+      </plugins>
+    </pluginManagement>
+  </build>
+</project>

trick16.1.7.2. Surefire

The Surefire Plugin is used during the test phase of the build lifecycle to execute the unit tests of an application. It generates reports in 2 different file formats: plain text and xml:

+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-surefire-plugin</artifactId>
+          <configuration>
+            <!--argLine>-Djava.awt.headless=true</argLine-->
+            <forkMode>once</forkMode>
+            <jvm>${baseJavaExecutable}</jvm>
+            <disableXmlReport>false</disableXmlReport>
+            <reportFormat>brief</reportFormat>
+            <trimStackTrace>false</trimStackTrace>
+            <printSummary>true</printSummary>
+          </configuration>
+        </plugin>
       </plugins>
     </pluginManagement>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-surefire-plugin</artifactId>
+      </plugin>
+    </plugins>
   </build>

Note

To skip testing supply the following command line option: -Dmaven.test.skip=true or -DskipTests=true.

The Surefire Report Plugin parses the generated TEST-*.xml files and renders them to Doxia which creates the web interface version of the test results.

+  <reporting>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-surefire-report-plugin</artifactId>
+        <version>2.12</version>
+        <configuration>
+          <aggregate>false</aggregate>
+          <linkXRef>false</linkXRef>
+          <showSuccess>true</showSuccess>
+        </configuration>
+        <reportSets>
+          <reportSet>
+            <reports>
+              <report>report-only</report>
+            </reports>
+          </reportSet>
+        </reportSets>
+      </plugin>
+    </plugins>
+  </reporting>
 </project>

trick16.1.7.3. Source

The Source Plugin creates a jar archive of the source files of the current project:

+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-source-plugin</artifactId>
+          <executions>
+            <execution>
+              <id>attach-sources</id>
+              <phase>verify</phase>
+              <goals>
+                <goal>jar-no-fork</goal>
+              </goals>
+              <configuration>
+                <attach>true</attach>
+                <includePom>true</includePom>
+                <excludeResources>false</excludeResources>
+              </configuration>
+            </execution>
+          </executions>
+        </plugin>
       </plugins>
     </pluginManagement>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-source-plugin</artifactId>
+      </plugin>
     </plugins>
   </build>

trick16.1.7.4. Javadoc

The Javadoc Plugin uses the Javadoc tool to package the generated javadocs into a jar file for distribution:

+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-javadoc-plugin</artifactId>
+          <configuration>
+            <javadocExecutable>${baseJavadocExecutable}</javadocExecutable>
+            <javadocVersion>${baseJavadocVersion}</javadocVersion>
+            <source>${baseJdkVersion}</source>
+            <quiet>true</quiet>
+            <detectJavaApiLink>false</detectJavaApiLink>
+            <detectOfflineLinks>false</detectOfflineLinks>
+            <breakiterator>true</breakiterator>
+            <show>protected</show>
+            <minmemory>128m</minmemory>
+            <maxmemory>256m</maxmemory>
+          </configuration>
+          <executions>
+            <execution>
+              <id>attach-javadoc</id>
+              <phase>verify</phase>
+              <goals>
+                <goal>jar</goal>
+              </goals>
+            </execution>
+          </executions>
+        </plugin>
       </plugins>
     </pluginManagement>

Important

Set <detectOfflineLinks/> to false because those links will be created as external links during site generation anyway and (see also issue MJAVADOC-275) to prevent build errors when using the javadoc goal before all project artifacts are installed in the verify phase).

+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-javadoc-plugin</artifactId>
+      </plugin>
     </plugins>
   </build>

Optionally configure Section A.3.2.1, “Javadoc report” for the project site.

trick16.1.7.5. Java software platform

Create modules for the JDKs 1.3 a.k.a. Kestrel, 1.4 a.k.a. Merlin, 1.5 a.k.a. Tiger, 1.6 a.k.a. Mustang and 1.7 a.k.a. Dolphin in W:\projects\maven-setup\base-pom\pom.xml:

   <contributors />
+
+  <modules>
+    <module>kestrel-base-pom</module>
+    <module>merlin-base-pom</module>
+    <module>tiger-base-pom</module>
+    <module>mustang-base-pom</module>
+    <module>dolphin-base-pom</module>
+  </modules>

In those modules configure the jvm specific properties of the currently configured plugins (for example for the Merlin 1.4 module) W:\projects\maven-setup\base-pom\merlin-base-pom\pom.xml:

+<?xml version="1.0" encoding="UTF-8"?>
+
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
+                             http://maven.apache.org/maven-v4_0_0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <parent>
+    <groupId>net.dev.freedumbytes.maven</groupId>
+    <artifactId>base-pom</artifactId>
+    <version>2.0-SNAPSHOT</version>
+  </parent>
+  <artifactId>merlin-base-pom</artifactId>
+  <packaging>pom</packaging>
+
+  <name>Free Dumb Bytes Merlin [1.4] POM</name>
+  <description>Java 1.4 Project Object Model.</description>
+  <inceptionYear>2010</inceptionYear>
+  <properties>
+    <baseJdkVersion>1.4</baseJdkVersion>
+    <baseJavadocVersion>1.42</baseJavadocVersion>
+    <baseJavacExecutable>${jdk.1.4.javac}</baseJavacExecutable>
+    <baseJavaExecutable>${jdk.1.4.jvm}</baseJavaExecutable>
+    <baseJavadocExecutable>${jdk.1.4.javadoc}</baseJavadocExecutable>
+  </properties>
+ </project>

Verify with mvn help:effective-pom in W:\projects\maven-setup\base-pom and W:\projects\maven-setup\base-pom\merlin-base-pom to see for example the difference between maven-javadoc-plugin settings.

trick16.1.8. Continuous integration

Browse to http://dev.net/jenkins/newView to create the following List Views: Application, Component, EOL and Sandbox.

Finally select the Component view http://dev.net/jenkins/view/Component/ and create a New Job in Jenkins with Job name Free Dumb Bytes Maven Setup to Build a maven2/3 project with the following settings:

  • Discard Old Builds with Days to keep builds 28.

  • Source Code Management for Git:

    • Repository URL: http://dev.net/git-repo/maven-setup.git (see also Section 14.1.4.4, “Git”).

    • Repository browser: FishEye.

      • URL: http://dev.net/fisheye/browse/maven-setup.

  • Build Triggers:

    • Build whenever a SNAPSHOT dependency is built: Checked.

    • Poll SCM:

      • Schedule: 0,10,20,30,40,50 * * * *.

        Caution

        Make sure the poll interval is larger than the quiet period otherwise the build will never start.

  • Build:

    • Root POM: pom.xml.

    • Goals and options: clean deploy.

  • Build Environment:

    • Post-Build Run Criteria: Run regardless of build result to make sure the unit test reports are also available when the build failed.

    • Select Add post-build step to Invoke top-level Maven targets:

      • Maven Version: M2_HOME.

      • Goals: site-deploy.

  • Post Steps:

    • E-mail Notification:

      • Send e-mail for every unstable build.

      • Send separate e-mails to individuals who broke the build.

  • Post-build Actions:

    • Allow broken build claiming.

Note

In case of the following error Cause: C:\Windows\System32\config\systemprofile\.m2\settings-security.xml (The system cannot find the file specified) during a Jenkins build make sure the Tomcat service is not running under the Local system account.

Tip

To keep the folder name short use the shorter git project name as Job name maven-setup and define under Advanced Project OptionsAdvanced... the Display Name Free Dumb Bytes Maven Setup.

trick16.1.9. Release

Let Jenkins take care of the snapshot deployments, but handle the release action from the command line with the Release Plugin.

The Nexus Repository is already configured as the default for deployments.

Make sure all local changes have been committed with commands:

git status
git log --oneline --decorate

Also check if all remote changes are up to date with command:

git remote show origin

To change the 2.0-SNAPSHOT version to a release 2.0 version, which also will be tagged in the SCM as setup-2.0, and to create the next 2.1-SNAPSHOT version use the command: mvn -Dusername=jjasper -Dpassword=password release:prepare (or try a Dry Run with the option -DdryRun=true followed by mvn release:clean to remove all of the created files).

Then deploy the release 2.0 version to Nexus using the command: mvn -Dusername=jjasper -Dpassword=password release:perform. This will result in a checkout of tag setup-2.0 into W:\projects\tzt\target\checkout from which the artifacts and sites will be deployed. Afterwards delete this directory otherwise it might show up in the Eclipse Team Synchronizing perspective.

Tip

Because Jenkins will overwrite the site with the next snapshot anyway save time and skip site-deploy and just run: mvn -Dusername=jjasper -Dpassword=password release:perform -Dgoals=deploy.

Important

The git scm provider fails with the following message fatal: .../maven-setup\base-pom\pom.xml is outside repository (see also SCM-667). This issue is fixed in maven-scm-plugin version 1.7.

trick16.1.10. Versions

The Release Plugin is handy for updating SNAPSHOT versions of the modules in a project. But when used on SNAPSHOT dependencies the next project SNAPSHOT version will be pointing to the next SNAPSHOT of the dependencies also. Which is usually not what is required. In comes the Versions Plugin option mvn versions:use-releases (for usage see also Section 17.3.4, “Publication”).

Look for updates of dependencies with mvn versions:display-dependency-updates and plugins with mvn versions:display-plugin-updates and the:

To lock the version of a SNAPSHOT for say a release candidate build use mvn versions:lock-snapshots and revert with mvn versions:unlock-snapshots.

To set the patch version for a branch version of for example 1.0 to 1.0.1-SNAPSHOT use mvn versions:set -DnewVersion=1.0.1-SNAPSHOT.

Remove the backup files with mvn versions:commit or revert changes with mvn versions:revert.

trick16.1.11. Application Integration overview

The Development Production Line in screenshots:

trick
Maven Setup About

Figure 16.1. Maven Setup About


trick
Nexus Maven Setup Release 2.0

Figure 16.2. Nexus Maven Setup Release 2.0


trick
Git Maven Setup Tags

Figure 16.3. Git Maven Setup Tags


trick
Eclipse Task MVNSTP-20

Figure 16.4. Eclipse Task MVNSTP-20


trick
Jenkins View Component

Figure 16.5. Jenkins View Component


trick
Jenkins Maven Setup Build

Figure 16.6. Jenkins Maven Setup Build


trick
Jenkins Maven Setup Build Changes

Figure 16.7. Jenkins Maven Setup Build Changes


trick
JIRA Issue MVNSTP-20

Figure 16.8. JIRA Issue MVNSTP-20


trick
FishEye Revisions MVNSTP-20

Figure 16.9. FishEye Revisions MVNSTP-20


trick
FishEye Changeset MVNSTP-20

Figure 16.10. FishEye Changeset MVNSTP-20


trick
FishEye Maven Setup Commit Graph

Figure 16.11. FishEye Maven Setup Commit Graph


trickChapter 17. Quality Assurance

Quality Assurance, or QA for short, refers to planned and systematic production processes that provide confidence in a product's suitability for its intended purpose.

trick17.1. Maven reports

Instead of configuring the Maven QA plugins, of which the output requires a lot of click around between those reports (see also screenshots) and the cross-reference, combine that information using Sonar for better evaluation.

trick17.2. Sonar

Sonar is about democratization of the source code quality concepts to be understandable and usable by every stakeholder in a development project.

trick17.2.1. Resources

trick17.2.2. Sonar installation guide

Download the archive: sonar-3.0.zip [version 3.0].

Extract this .zip file to P:\dev\apps\qa.

trickPress Windows Logo+Break keys to open the Windows System Properties. Select Advanced system settingsEnvironment Variables and Edit the Path to append %SONAR_HOME%\bin\windows-x86-32;. Also add a New system variable SONAR_HOME pointing to P:\dev\apps\qa\sonar-3.0.

Change the context 3, the listening port 2 and restricted to localhost 1 by editing the configuration file P:\dev\apps\qa\sonar-3.0\conf\sonar.properties:

#---------------------------------------------------------
# WEB SETTINGS - STANDALONE MODE ONLY
# These settings are ignored when the war file is deployed to a JEE server.
#---------------------------------------------------------
sonar.web.host:                           127.0.0.1trick1
sonar.web.port:                           8072trick2
sonar.web.context:                        /sonartrick3

trick17.2.2.1. Database settings

Create a MySQL user called sonar-user and database called sonar with the following commands:

mysql -u root -p
mysql> create database sonar character set utf8 collate utf8_general_ci;
mysql> grant select, insert, update, delete, create, drop, alter, index on sonar.*
    ->  to 'sonar-user'@'localhost' identified by 'password';
mysql> flush privileges;
mysql> select host,user from mysql.user;
mysql> select host,db,user from mysql.db;
mysql> quit

Configure the Sonar application server to connect to MySQL 1-6 with url 4 jdbc:mysql://localhost:3306/sonar?useUnicode=true&characterEncoding=utf8&rewriteBatchedStatements=true by editing the configuration file P:\dev\apps\qa\sonar-3.0\conf\sonar.properties:

#----- Credentials
# Permissions to create tables and indexes must be granted to JDBC user.
# The schema must be created first.
sonar.jdbc.username:                       sonar-usertrick1
sonar.jdbc.password:                       passwordtrick2

#----- Embedded database Derby
# Comment the following line to deactivate the default embedded database.
#sonar.jdbc.url:                            jdbc:derby://localhost:1527/sonar;create=truetrick3

#----- MySQL 5.x/6.x
# Comment the embedded database and uncomment the following lines to use MySQL
sonar.jdbc.url:                            jdbc:mysql://localhost:3306/sonar?...trick4 (see above)

# Optional properties
sonar.jdbc.driverClassName:                com.mysql.jdbc.Drivertrick5
sonar.jdbc.validationQuery:                select 1trick6

#----- Connection pool settings
sonar.jdbc.maxActive:                      20
sonar.jdbc.maxIdle:                        5
sonar.jdbc.minIdle:                        2
sonar.jdbc.maxWait:                        5000
#sonar.jdbc.minEvictableIdleTimeMillis:     600000trick7
#sonar.jdbc.timeBetweenEvictionRunsMillis:  30000trick7

Important

Don't forget to comment the lines 3 and 7 to deactivate the default embedded database settings.

trick17.2.3. Upgrading

After starting Sonar browse to http://localhost:8072/sonar/updatecenter/system_updates to upgrade the database (see also Upgrade guide).

trick17.2.4. Sonar configuration

Verify the installation by running StartSonar.bat.

Important

In case of the following error Startup failed: Timed out waiting for a signal from the JVM when using jdk 1.7, just use jdk 1.6 instead 1 in P:\dev\apps\qa\sonar-3.0\conf\wrapper.conf:

# JVM
# Can be an absolute path, for example:
#wrapper.java.command=/path/to/my/jdk/bin/java
wrapper.java.command=P:\dev\apps\prg\java\jdk1.6.0_37\bin\javatrick1

Verify that the server is running in your browser at http://localhost:8072/sonar. Click Log in as admin with password admin. Click Administrator to change the password.

trick17.2.4.1. Update Center

Select ConfigurationUpdate CenterAvailable Plugins and for example select the following plugins from the Sonar Plugin Library:

Restart Sonar.

trick17.2.4.2. Settings

Select ConfigurationGeneral Settings and configure:

  • Clover:

  • Code Coverage:

    • Code coverage plugin: clover and Save Code Coverage Settings.

  • SCM Activity:

    • Password: password.

    • Enable loading of SCM activity: true.

    • User: sonar and Save SCM Activity Settings.

    Note

    In case of performance issues configure this in the project specific settings.

trick17.2.4.3. Quality profiles

Select ConfigurationQuality Profiles and Create profile (see also Section A.3.2.3, “Maven QA reports”):

  • Name: Free Dumb Bytes dev.net.

  • Checkstyle XML: W:\projects\qa-sandbox\src\qa-config\checkstyle.xml.

  • Findbugs XML: W:\projects\qa-sandbox\src\qa-config\findbugs-include.xml.

  • PMD XML: W:\projects\qa-sandbox\src\qa-config\pmd-java.xml and click Create Java profile and Set as default.

trick17.2.5. Apache configuration

Instruct Apache to proxy all URLs whose path portions begin with /sonar/ using the following P:\dev\apps\httpserver\apache-conf\httpd-vhosts.conf include 1:

<VirtualHost *:80>
    ...

    <IfModule proxy_module>
    <IfModule proxy_http_module>
        ...

        <Proxy *>
            ...
        </Proxy>

        # Sonar
        Include ../apache-conf/httpd-sonar.conftrick1
    </IfModule>
    </IfModule>
</VirtualHost>

with the following content in P:\dev\apps\httpserver\apache-conf\httpd-sonar.conf:

<IfModule proxy_module>
<IfModule proxy_http_module>
    <Location /sonar>
        Include ../apache-conf/httpd-realm.conf
    </Location>

    ProxyPass /sonar        http://localhost:8072/sonar
    ProxyPassReverse /sonar http://localhost:8072/sonar
</IfModule>
</IfModule>

When the Apache HTTP Server is restarted you should be able to browse Sonar at http://dev.net/sonar.

trick17.2.6. Windows service

To restart automatically on Microsoft Windows, create a Windows service. Use the Tanuki Java Service Wrapper shipped with Sonar.

Optionally edit the following entries 1-5 in the service wrapper configuration file P:\dev\apps\qa\sonar-3.0\conf\wrapper.conf:

# Java Additional Parameters
wrapper.java.additional.1=-Djava.awt.headless=true
wrapper.java.additional.2=-XX:MaxPermSize=128m192mtrick1

#********************************************************************
# Wrapper Windows Properties
#********************************************************************
# Title to use when running as a console
wrapper.console.title=Sonardev.net Sonartrick2

#********************************************************************
# Wrapper Windows NT/2000/XP Service Properties
#********************************************************************
# WARNING - Do not modify any of these properties when an application
#  using this configuration file has been installed as a service.
#  Please uninstall the service before modifying this section.  The
#  service can then be reinstalled.

# Name of the service
wrapper.ntservice.name=Sonarsonartrick3

# Display name of the service
wrapper.ntservice.displayname=Sonardev.net Sonartrick4

# Description of the service
wrapper.ntservice.description=SonarSonar is an open source quality management platform.trick5

Register the Sonar service with the command: %SONAR_HOME%\bin\windows-x86-32\InstallNTService.bat. Start Sonar with net start sonar.

Important

In case of the following error Startup failed: Timed out waiting for a signal from the JVM when using jdk 1.7, just use jdk 1.6 instead 1 in P:\dev\apps\qa\sonar-3.0\conf\wrapper.conf:

# JVM
# Can be an absolute path, for example:
#wrapper.java.command=/path/to/my/jdk/bin/java
wrapper.java.command=P:\dev\apps\prg\java\jdk1.6.0_37\bin\javatrick1

trick17.2.7. Maven integration

Configure Maven to enable command line action mvn sonar:sonar on the build server with a sonar profile in the Maven configuration file P:\dev\apps\build\apache-maven-3.0.4\conf\settings.xml:

  <profiles>
    ...

    <profile>
      <id>sonar</id>
      <activation>
        <activeByDefault>true</activeByDefault>
      </activation>
      <properties>
        <sonar.jdbc.url>
          jdbc:mysql://localhost:3306/sonar?useUnicode=true&amp;characterEncoding=utf8&amp;rewriteBatchedStatements=true
        </sonar.jdbc.url>
        <sonar.jdbc.username>sonar-user</sonar.jdbc.username>
        <sonar.jdbc.password>password</sonar.jdbc.password>
        <sonar.jdbc.driver>com.mysql.jdbc.Driver</sonar.jdbc.driver>
        <sonar.host.url>http://localhost:8072/sonar</sonar.host.url>
      </properties>
    </profile>
  </profiles>

The Sonar Maven Report Plugin adds a report link to the Maven site, that redirects to the project dashboard in Sonar (W:\projects\maven-setup\pom.xml):

+      <plugin>
+        <groupId>org.codehaus.sonar-plugins</groupId>
+        <artifactId>maven-report</artifactId>
+        <version>0.1</version>
+        <configuration>
+          <sonar.host.url>http://dev.net/sonar</sonar.host.url>
+        </configuration>
+      </plugin>
     </plugins>
   </reporting>
 </project>

Update the site descriptor in W:\projects\maven-setup\src\site\site.xml:

       <item name="Jenkins" href="http://dev.net/jenkins" />
+      <item name="Sonar" href="http://dev.net/sonar" />

trick17.2.8. Jenkins integration

When the Jenkins Sonar Plugin is installed it is possible to restrict the prior mentioned Maven Integration to the build server only.

To activate Sonar for a project select for example JenkinsFree Dumb Bytes Quality Assurance Sandbox and Configure:

  • Post-build Actions:

    • Sonar.

With these global Trigger Exclusions settings the Sonar Plugin is only run on manual triggered builds. And thus makes for a good alternative to the command line usage mvn sonar:sonar.

trick17.2.9. Maven vs Sonar Quality Assurance reports comparison

To get an idea of the difference between the QA reports of Maven and Sonar take a look at the following screenshots:

trick
Maven QA Sandbox FindBugs Report

Figure 17.1. Maven QA Sandbox FindBugs Report


trick
Maven QA Sandbox PMD Report

Figure 17.2. Maven QA Sandbox PMD Report


trick
Maven QA Sandbox Checkstyle Report

Figure 17.3. Maven QA Sandbox Checkstyle Report


trick
Maven QA Sandbox JXR Source XRef (still remembered what violation at which line?)

Figure 17.4. Maven QA Sandbox JXR Source XRef (still remembered what violation at which line?)


trick
Maven QA Sandbox Sonar Violations Drilldown (all violations at one glance)

Figure 17.5. Maven QA Sandbox Sonar Violations Drilldown (all violations at one glance)


trick
Maven QA Sandbox Sonar Dashboard

Figure 17.6. Maven QA Sandbox Sonar Dashboard


trick
Maven QA Sandbox Sonar Hotspots

Figure 17.7. Maven QA Sandbox Sonar Hotspots


trick
Maven QA Sandbox Sonar Timemachine

Figure 17.8. Maven QA Sandbox Sonar Timemachine


trick17.3. jDocBook

The purpose of the jDocBook Plugin is to allow the DocBook transformations to occur as a natural part of the users Maven build. It is used to create this documentation from the master.xml.

trick17.3.1. Docbook configuration

Lets setup a base configuration, for Maven Docbooks to come, with the following JIRA project:

  • Maven Docbook [MVNDBK]: Maven docbook configuration. (for the source see Appendix D, Source)

    With the following components:

    1. docbook: Docbook configuration.

    and versions:

    • 1.0 - HTML and PDF generation.

Start a new Git repository maven-docbook by calling http://dev.net/git-repo?pn=maven-docbook&pd=Maven+docbook+configuration&a=create direct or through the GitWeb user interface.

Clone this remote repository with the following command git-clone jjasper maven-docbook.

Start out with the Look and Feel of the PressGang, which is the centralized hub JBoss projects can use to get assistance with documentation. If you have any questions about writing professional open source documentation using DocBook XML, you've come to the right place to have them answered.

Create the maven-docbook initial settings POM in W:\projects\maven-docbook\pom.xml:

+<?xml version="1.0" encoding="UTF-8"?>
+
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
+                             http://maven.apache.org/maven-v4_0_0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <parent>
+    <groupId>net.dev.freedumbytes.maven</groupId>
+    <artifactId>base-pom</artifactId>
+    <version>2.1</version>
+  </parent>
+
+  <groupId>net.dev.freedumbytes.documentation</groupId>
+  <artifactId>docbook</artifactId>
+  <version>1.0-SNAPSHOT</version>
+  <packaging>pom</packaging>
+
+  <name>Free Dumb Bytes DocBook Documentation</name>
+  <description>Common setup for all Free Dumb Bytes DocBook documentation.</description>
+  <url>http://dev.net/mvn-sites/maven-docbook</url>
+  <inceptionYear>2010</inceptionYear>
+  <scm>
+    <developerConnection>scm:git:http://dev.net/git-repo/maven-docbook.git</developerConnection>
+    <url>http://dev.net/fisheye/browse/maven-docbook</url>
+  </scm>
+  <distributionManagement>
+    <site>
+      <id>mvn-sites</id>
+      <name>Maven Documentation Sites</name>
+      <url>dav:http://dev.net/mvn-sites/maven-docbook</url>
+    </site>
+  </distributionManagement>
+  <properties>
+    <translation>en-US</translation>
+  </properties>
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.jboss.maven.plugins</groupId>
+        <artifactId>maven-jdocbook-plugin</artifactId>
+        <version>2.3.7</version>
+        <extensions>true</extensions>
+        <dependencies>
+          <dependency>
+            <groupId>org.jboss.pressgang</groupId>
+            <artifactId>pressgang-jdocbook-style</artifactId>
+            <type>jdocbook-style</type>
+            <version>3.0.0</version>
+          </dependency>
+          <dependency>
+            <groupId>org.jboss.pressgang</groupId>
+            <artifactId>pressgang-xslt-ns</artifactId>
+            <version>3.0.0</version>
+          </dependency>
+        </dependencies>
+        <configuration>
+          <sourceDirectory>${project.basedir}/src/docbook</sourceDirectory>
+          <sourceDocumentName>master.xml</sourceDocumentName>
+          <masterTranslation>${translation}</masterTranslation>
+          <imageResource>
+            <directory>${project.basedir}/src/docbook/${translation}</directory>
+            <includes>
+              <include>**/*.svg</include>
+              <include>**/*.png</include>
+              <include>**/*.jpg</include>
+              <include>**/*.gif</include>
+              <include>**/*.bmp</include>
+            </includes>
+          </imageResource>
+          <cssResource>
+            <directory>${project.basedir}/src/docbook/${translation}</directory>
+            <includes>
+              <include>**/*.css</include>
+            </includes>
+          </cssResource>
+          <formats>
+            <format>
+              <formatName>html</formatName>
+              <stylesheetResource>classpath:/xslt/org/jboss/pressgang/xhtml.xsl</stylesheetResource>
+              <finalName>index.html</finalName>
+            </format>
+            <format>
+              <formatName>pdf</formatName>
+              <stylesheetResource>classpath:/xslt/org/jboss/pressgang/pdf.xsl</stylesheetResource>
+              <finalName>${project.name}.pdf</finalName>
+            </format>
+          </formats>
+          <options>
+            <xmlTransformerType>saxon</xmlTransformerType>
+            <xincludeSupported>true</xincludeSupported>
+            <useRelativeImageUris>true</useRelativeImageUris>
+          </options>
+        </configuration>
+      </plugin>
+    </plugins>
+  </build>
+</project>

In Eclipse create a Working Set Maven Docbook and import this Maven Docbook project into it with FileImport...MavenExisting Maven Projects from Root directory W:\projects\maven-docbook and click Finish.

With this setup the Development Production Line manual would look something like this:

trick
Development Production Line - PressGang Look and Feel

Figure 17.9. Development Production Line - PressGang Look and Feel


Important

When building a jDocBook using maven in combination with java.home pointing to a jdk1.7 the following error occured: Failure reading http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/chunk.xsl: Connection timed out: connect. Just update MAVEN_OPTS as mentioned in the Maven installation guide.

trick17.3.2. Documentation setup

Lets setup a base structure, for Maven Documentation Customization, with the following JIRA project:

  • Maven Docs [MVNDCS]: Maven documentation setup. (for the source see Appendix D, Source)

    With the following components:

    1. docs: Documentation setup.

    2. style: Custom HTML and PDF styling.

    3. xslt: Custom XHTML and PDF XSLTs.

    and versions:

    • 1.0 - Custom Look and Feel.

Note

This second project is necessary because the custom style and xslt, that will be defined in maven-docs and used in maven-docbook, cause a chicken and egg problem because those artifacts are referenced as dependencies for the jdocbook plugin during the build.

Start a new Git repository maven-docs by calling http://dev.net/git-repo?pn=maven-docs&pd=Maven+documentation+setup&a=create direct or through the GitWeb user interface.

Clone this remote repository with the following command git-clone jjasper maven-docs.

Create the maven-docs minimal project base POM in W:\projects\maven-docs\pom.xml:

+<?xml version="1.0" encoding="UTF-8"?>
+
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
+                             http://maven.apache.org/maven-v4_0_0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <parent>
+    <groupId>net.dev.freedumbytes.maven</groupId>
+    <artifactId>base-pom</artifactId>
+    <version>2.1</version>
+  </parent>
+
+  <groupId>net.dev.freedumbytes.documentation</groupId>
+  <artifactId>docs</artifactId>
+  <version>1.0-SNAPSHOT</version>
+  <packaging>pom</packaging>
+
+  <name>Free Dumb Bytes Documentation</name>
+  <description>Free Dumb Bytes documentation setup.</description>
+  <url>http://dev.net/mvn-sites/maven-docs</url>
+  <inceptionYear>2010</inceptionYear>
+  <scm>
+    <developerConnection>scm:git:http://dev.net/git-repo/maven-docs.git</developerConnection>
+    <url>http://dev.net/fisheye/browse/maven-docs</url>
+  </scm>
+  <distributionManagement>
+    <site>
+      <id>mvn-sites</id>
+      <name>Maven Documentation Sites</name>
+      <url>dav:http://dev.net/mvn-sites/maven-docs</url>
+    </site>
+  </distributionManagement>
+  <modules>
+    <module>custom-docbook-style</module>
+    <module>custom-docbook-xslt</module>
+  </modules>
+  <properties>
+    <jdocbookPluginVersion>2.3.7</jdocbookPluginVersion>
+    <jdocbookStylePluginVersion>2.0.0</jdocbookStylePluginVersion>
+    <jbossPressgangVersion>3.0.0</jbossPressgangVersion>
+    <docbookXslVersion>1.76.1</docbookXslVersion>
+  </properties>
+</project>

Create the maven-docs minimal style module POM in W:\projects\maven-docs\custom-docbook-style\pom.xml:

+  <parent>
+    <groupId>net.dev.freedumbytes.documentation</groupId>
+    <artifactId>docs</artifactId>
+    <version>1.0-SNAPSHOT</version>
+  </parent>
+
+  <artifactId>custom-docbook-style</artifactId>
+  <packaging>jdocbook-style</packaging>
+
+  <name>Free Dumb Bytes Documentation Styles</name>
+  <description>Custom HTML and PDF styling.</description>
+  <inceptionYear>2010</inceptionYear>
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.jboss.maven.plugins</groupId>
+        <artifactId>maven-jdocbook-style-plugin</artifactId>
+        <version>${jdocbookStylePluginVersion}</version>
+        <extensions>true</extensions>
+        <configuration>
+          <cssSourceDirectory>${basedir}/src/docbook/custom-css</cssSourceDirectory>
+          <imagesSourceDirectory>${basedir}/src/docbook/custom-images</imagesSourceDirectory>
+          <fontSourceDirectory>${basedir}/src/docbook/custom-fonts</fontSourceDirectory>
+          <xsltSourceDirectory>${basedir}/src/docbook/custom-xslt</xsltSourceDirectory>
+        </configuration>
+      </plugin>
+    </plugins>
+  </build>
+</project>

Create the maven-docs minimal xslt module POM in W:\projects\maven-docs\custom-docbook-xslt\pom.xml:

+  <parent>
+    <groupId>net.dev.freedumbytes.documentation</groupId>
+    <artifactId>docs</artifactId>
+    <version>1.0-SNAPSHOT</version>
+  </parent>
+
+  <artifactId>custom-docbook-xslt</artifactId>
+
+  <name>Free Dumb Bytes Documentation XSLT</name>
+  <description>Custom XHTML and PDF XSLTs.</description>
+  <inceptionYear>2010</inceptionYear>
+  <dependencies>
+    <dependency>
+      <groupId>net.sf.docbook</groupId>
+      <artifactId>docbook-xsl</artifactId>
+      <version>${docbookXslVersion}</version>
+      <classifier>ns-resources</classifier>
+      <type>zip</type>
+    </dependency>
+    <dependency>
+      <groupId>org.jboss.pressgang</groupId>
+      <artifactId>pressgang-highlight</artifactId>
+      <version>${jbossPressgangVersion}</version>
+    </dependency>
+  </dependencies>
+</project>

In Eclipse create a Working Set Maven Docs and import this Maven Docs project into it with FileImport...MavenExisting Maven Projects from Root directory W:\projects\maven-docs and click Finish.

Make an anynomous clone from the pressgang-tools with:

cd /d W:\projects 
git clone http://github.com/pressgang/pressgang-tools

cd \projects\pressgang-tools
git tag -l
git checkout pressgang-tools-3.0.0

cd \projects\pressgang-tools\pressgang-jdocbook-style\src\main
xcopy /S /I css\*.css ^
      W:\projects\maven-docs\custom-docbook-style\src\docbook\custom-css
xcopy /S /I images\*.svg ^
      W:\projects\maven-docs\custom-docbook-style\src\docbook\custom-images
xcopy /S /I images\*.png ^
      W:\projects\maven-docs\custom-docbook-style\src\docbook\custom-images
xcopy /S /I images\*.gif ^
      W:\projects\maven-docs\custom-docbook-style\src\docbook\custom-images

cd \projects\pressgang-tools\pressgang-xslt-ns\src\main
xcopy /S /I resources\xslt\*.xsl ^
      W:\projects\maven-docs\custom-docbook-xslt\src\main\resources\xslt

cd \projects\maven-docs
mvn clean install

Configure the maven-docbook POM in W:\projects\maven-docbook\pom.xml to use the just installed custom modules:

   <parent>
-    <groupId>net.dev.freedumbytes.maven</groupId>
-    <artifactId>base-pom</artifactId>
-    <version>2.1</version>
+    <groupId>net.dev.freedumbytes.documentation</groupId>
+    <artifactId>docs</artifactId>
+    <version>1.0-SNAPSHOT</version>
   </parent>
 
-  <groupId>net.dev.freedumbytes.documentation</groupId>
   <artifactId>docbook</artifactId>
   <version>1.0-SNAPSHOT</version>
   <properties>
+    <mavenDocsVersion>1.0-SNAPSHOT</mavenDocsVersion>
     <translation>en-US</translation>
   </properties>
       <plugin>
         <groupId>org.jboss.maven.plugins</groupId>
         <artifactId>maven-jdocbook-plugin</artifactId>
-        <version>2.3.7</version>
+        <version>${jdocbookPluginVersion}</version>
         <extensions>true</extensions>
         <dependencies>
           <dependency>
-            <groupId>org.jboss.pressgang</groupId>
-            <artifactId>pressgang-jdocbook-style</artifactId>
-            <version>3.0.0</version>
+            <groupId>net.dev.freedumbytes.documentation</groupId>
+            <artifactId>custom-docbook-style</artifactId>
+            <version>${mavenDocsVersion}</version>
             <type>jdocbook-style</type>
           </dependency>
           <dependency>
-            <groupId>org.jboss.pressgang</groupId>
-            <artifactId>pressgang-xslt-ns</artifactId>
-            <version>3.0.0</version>
+            <groupId>net.dev.freedumbytes.documentation</groupId>
+            <artifactId>custom-docbook-xslt</artifactId>
+            <version>${mavenDocsVersion}</version>
           </dependency>
         </dependencies>

Customize the Look and Feel:

  • MVNDBK-1: Create the minimal POM with PressGang Look and Feel.

  • MVNDCS-1: Create the minimal POMs for custom Look and Feel modules.

  • MVNDCS-2: Initialize custom style based on PressGang style.

  • MVNDCS-3: Initialize custom xslt based on PressGang xslt.

  • MVNDBK-2: Switch to custom Look and Feel artifacts.

  • MVNDCS-4: Refactor initial PressGang xslt.

  • MVNDCS-5: Refactor initial PressGang style.

  • MVNDBK-3: Switch to refactored XSLs.

  • MVNDCS-7: Reenable status draft.

  • MVNDCS-8: Customize admonitions.

  • MVNDCS-9: Customize list style.

  • MVNDCS-10: Customize code style.

  • MVNDCS-11: Customize link style.

  • MVNDCS-12: Support role strikethrough.

  • MVNDCS-13: Support element accel.

  • MVNDCS-14: Wrap long lists of menu choices.

  • MVNDCS-15: Screen and printer output improvements.

  • MVNDCS-16: Customize community imagery.

  • MVNDCS-17: Highlight chapters and appendices in the table of content.

  • MVNDCS-18: Reenable unused callout XSLs.

  • MVNDCS-19: Fix unwanted line breaks before anchors.

  • MVNDCS-20: Customize navigation.

  • MVNDCS-21: Highlight gui, application and command elements.

  • MVNDCS-22: Customize title page.

  • MVNDCS-23: Customize pagesetup.

  • MVNDCS-24: Uniform menuchoice separator.

  • MVNDCS-25: Create security confidential mode.

  • MVNDCS-26: Highlight xref links.

  • MVNDBK-4: Activate hyphenation.

With this custom setup the Development Production Line manual looks something like this:

trick
Development Production Line - Custom Look and Feel

Figure 17.10. Development Production Line - Custom Look and Feel


Important

When building a jDocBook using maven in combination with java.home pointing to a jdk1.7 the following error occured: Failure reading http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/chunk.xsl: Connection timed out: connect. Just update MAVEN_OPTS as mentioned in the Maven installation guide.

trick17.3.3. Hyphenation

The PDFs are generated with FOP. Apache FOP (Formatting Objects Processor) is a print formatter driven by XSL formatting objects (XSL-FO) and an output independent formatter. FOP uses Liang's hyphenation algorithm, well known from TeX. It needs language specific pattern and other data for operation. Because of licensing issues (and for convenience), all hyphenation patterns for FOP are made available through the Objects For Formatting Objects project (OFFO).

To activate hyphenation for jDocBook Plugin add a dependency to OFFO:

Index: docbook/pom.xml
===================================================================
             <version>1.0</version>
             <type>jdocbook-style</type>
           </dependency>
+          <dependency>
+            <groupId>net.sf.offo</groupId>
+            <artifactId>fop-hyph</artifactId>
+            <version>1.2</version>
+          </dependency>
         </dependencies>
         <configuration>
           <sourceDocumentName>master.xml</sourceDocumentName>

trick17.3.4. Publication

Make sure all local changes have been committed with commands for both maven-docs and maven-docbook:

git status
git log --oneline --decorate

Also check if all remote changes are up to date with command:

git remote show origin

Release the maven-docs project:

mvn -Dusername=jjasper -Dpassword=password release:prepare
mvn -Dusername=jjasper -Dpassword=password release:perform -Dgoals=deploy

Upgrade the maven-docbook project to use this release of maven-docs:

mvn versions:update-parent
[INFO] Updating parent from 1.0-SNAPSHOT to 1.0
mvn versions:commit

mvn versions:update-properties
[INFO] Updated ${mavenDocsVersion} from 1.0-SNAPSHOT to 1.0
mvn versions:commit

git push or create an upgrade issue in Eclipse and commit; thus tracking every commit in JIRA.

Release the maven-docbook project itself:

mvn -Dusername=jjasper -Dpassword=password release:prepare
mvn -Dusername=jjasper -Dpassword=password release:perform -Dgoals=deploy

trickAppendix A. Tips & Tricks

trickA.1. Archives

trickA.1.1. How to extract content from MSI files

While there are plenty of utilities available to extract the contents of an MSI file, you can do it straight from the command line: msiexec /a file.msi /qb TARGETDIR=folder.

trickA.2. Eclipse

trickA.2.1. Patch, test and build an Eclipse plugin

As an example we use the patch 138216 from issue 41097. Download this patch to W:\download\org.eclipse.team.cvs.core.R3_4_1_maintenance.patch.txt.

Next open Eclipse and select FileImport...CVSProjects from CVS and click Next to Create a new repository location (if it isn't already there) with:

  • Host: dev.eclipse.org

  • Repository path: /cvsroot/eclipse

  • User: anonymous

  • Connection type: pserver and click Next.

From this repository fetch project as follows:

  • Select Use an existing module: org.eclipse.team.cvs.core and click Next.

  • Select Checkout as a project in the workspace with Checkout subfolders checked and click Next.

  • Check Use the default workspace location and click Next.

  • Refresh Tags and select from BranchesR3_4_1_maintenance_patches and click Finish.

After the import select WindowOpen perspectiveOther...Java to apply the patch as follows:

  • On org.eclipse.team.cvs.core right-click and select TeamApply Patch....

  • Find the downloaded file W:\download\org.eclipse.team.cvs.core.R3_4_1_maintenance.patch.txt and click Next and Finish.

Testing the patch can be done as follows:

  • Just select WindowOpen perspectiveOther...Java.

  • And open org.eclipse.team.cvs.coreplugin.xml.

  • Open the Overview tab of the plugin.xml and click Launch an Eclipse application to start an new Eclipse test instance that will be using this patched version of the plugin.

  • Close the Eclipse test instance.

Rebuild this plug-in as follows:

  • FileExport...Plug-in DevelopmentDeployable plug-ins and fragments and click Next.

  • In the Available Plug-ins and Fragments check org.eclipse.team.cvs.core.

  • Set DestinationDirectory to for example W:\download.

    Important

    When patching an Eclipse core plugin make sure to set the OptionsQualifier replacement to that of the jar that is already in use, in this case r34x_20090115 (see P:\dev\apps\ide\eclipse\plugins). Furthermore check that the MANIFEST.MF Bundle-Version: 3.3.101.qualifier is using the text qualifier in its definition and has the same version number as the original plugin jar: org.eclipse.team.cvs.core_3.3.101.r34x_20090115.jar. Otherwise you have to start messing around with those numbers in bundles.info, content.xml and feature.xml files.

and click Finish to generate a new Eclipse plugin jar.

Important

After replacing the original plugin jar start Eclipse with the extra option -clean otherwise the new features might not work. In this case the new extension sspi didn't showup at first.

trickA.2.2. Repository Browsing

trickA.2.2.1. Git repository

Set the following Perspective preferences to browse the Git repositories:

  • Left click on the icon Open Perspective and select Other... to add the Git Repository Exploring shortcut .

  • In the active Git Repositories view click the Add an existing local Git Repository icon to Search for repositories:

    • Directory: W:\projects, select the required ones and click Finish.

trickA.2.2.2. Subversion repository

Set the following Perspective preferences to browse the Subversion repository:

  • Left click on the icon Open Perspective and select Other... to add the SVN Repository Exploring shortcut .

  • In the active SVN Repositories view click the Windows Application key or Shift+F10 to add a NewRepository Location...:

    • Url: http://jjasper@dev.net/svn-repo/ and click Finish.

trickA.2.2.3. CVS repository

Set the following Perspective preferences to browse the CVS repository:

  • Left click on the icon Open Perspective and select Other... to add the CVS Repository Exploring shortcut .

  • In the active CVS Repositories view click the Windows Application key or Shift+F10 (or right click in the view) to add a NewRepository Location...:

    Important

    Connection type: ext is also possible because the protocol is handled by the extnt.exe client application; sspi is just there to handle modules, that were checked out using this protocol. Because then all CVS\Root files will contain entries like :sspi:jjasper@dev.net:/cvs-repo or :sspi:jjasper@192.168.0.xx:/cvs-repo.

trickA.2.2.4. Maven Integration Extras

Check for the Maven Integration Extras with WindowPreferencesMavenDiscoveryOpen Catalog to search for M2E related stuff in the Marketplace - An App Store for the Eclipse Ecosystem (see also HelpEclipse Marketplace...). Select the following from m2e Team providers:

  • m2e-egit

  • m2e-subclipse

    Note

    It doesn't support Subclipse 1.8 (see also m2eclipse-subclipse issue 3). This only means it isn't possible to use FileImport...MavenCheck out Maven Projects from SCM. But when the projects are checked out into a projects folder and are imported with FileImport...MavenExisting Maven Projects anyway, it doesn't matter because Team Synchronizing works.

  • m2e-cvs and click Finish.

trickA.3. Project

trickA.3.1. Custom skins

Lets setup a base structure, for Maven skins to come, with the following JIRA project:

  • Maven Skins [MVNSKN]: Maven custom skins. (for the source see Appendix D, Source)

    With the following components:

    1. paper: Paperlike skin.

    2. fluido: Apache Maven Fluido skin enhancement.

    and versions:

    • 1.0 - Paper skin.

    • 1.1 - Fluido skin.

Start a new Git repository maven-skins by calling http://dev.net/git-repo?pn=maven-skins&pd=Maven+custom+skins&a=create direct or through the GitWeb user interface.

Clone this remote repository with the following command git-clone jjasper maven-skins.

Create the minimal base POM in W:\projects\maven-skins\pom.xml:

+<?xml version="1.0" encoding="UTF-8"?>
+
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
+                             http://maven.apache.org/maven-v4_0_0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <parent>
+    <groupId>net.dev.freedumbytes.maven</groupId>
+    <artifactId>setup</artifactId>
+    <version>2.0</version>
+  </parent>
+  <groupId>net.dev.freedumbytes.maven.skins</groupId>
+  <artifactId>maven-skins</artifactId>
+  <version>1.0-SNAPSHOT</version>
+  <packaging>pom</packaging>
+  <name>Free Dumb Bytes Maven Skins</name>
+  <description>Setup the site skins.</description>
+  <url>http://dev.net/mvn-sites/maven-skins</url>
+  <inceptionYear>2010</inceptionYear>
+  <developers>
+    <developer>
+      <id>jjasper</id>
+      <name>Jene Jasper</name>
+      <email>jjasper@dev.java.net</email>
+      <organization>Free Dumb Bytes</organization>
+      <organizationUrl>http://dev.net</organizationUrl>
+      <roles>
+        <role>developer</role>
+      </roles>
+      <timezone>+1</timezone>
+    </developer>
+  </developers>
+
+  <contributors />
+  <scm>
+    <developerConnection>scm:git:http://dev.net/git-repo/maven-skins.git</developerConnection>
+    <url>http://dev.net/fisheye/browse/maven-skins</url>
+  </scm>
+  <distributionManagement>
+    <site>
+      <id>mvn-sites</id>
+      <name>Maven Documentation Sites</name>
+      <url>dav:http://dev.net/mvn-sites/maven-skins</url>
+    </site>
+  </distributionManagement>
+</project>

In Eclipse create a Working Set Maven Skins and import this Maven Skins project into it with FileImport...MavenExisting Maven Projects from Root directory W:\projects\maven-skins and click Finish.

trickA.3.1.1. Custom Paper Skin

To create a paperlike skin export a copy of maven-default-skin-1.1:

cd /d W:\projects
svn export ^
    http://svn.apache.org/repos/asf/maven/skins/tags/maven-default-skin-1.1 ^
    maven-default-skin-1.1

Copy the theme into project maven-skins:

cd maven-default-skin-1.1
xcopy /S /I src\*.css W:\projects\maven-skins\maven-paper-skin\src
xcopy /S /I src\*.gif W:\projects\maven-skins\maven-paper-skin\src
xcopy /S /I src\*.png W:\projects\maven-skins\maven-paper-skin\src

Commit those files:

  1. maven-skins/maven-paper-skin/src/main/resources/css/maven-theme.css

  2. maven-skins/maven-paper-skin/src/main/resources/images/icon_error_sml.gif

  3. maven-skins/maven-paper-skin/src/main/resources/images/icon_info_sml.gif

  4. maven-skins/maven-paper-skin/src/main/resources/images/icon_success_sml.gif

  5. maven-skins/maven-paper-skin/src/main/resources/images/icon_warning_sml.gif

  6. maven-skins/maven-paper-skin/src/main/resources/images/external.png

  7. maven-skins/maven-paper-skin/src/main/resources/images/newwindow.png

Define a new module maven-paper-skin in W:\projects\maven-skins\pom.xml:

   </distributionManagement>
+
+  <modules>
+    <module>maven-paper-skin</module>
+  </modules>
 </project>

Supply the new module W:\projects\maven-skins\maven-paper-skin\pom.xml:

+<?xml version="1.0" encoding="UTF-8"?>
+
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
+                             http://maven.apache.org/maven-v4_0_0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <parent>
+    <groupId>net.dev.freedumbytes.maven.skins</groupId>
+    <artifactId>maven-skins</artifactId>
+    <version>1.0-SNAPSHOT</version>
+  </parent>
+  <artifactId>maven-paper-skin</artifactId>
+  <packaging>jar</packaging>
+
+  <name>Free Dumb Bytes Paper Skin</name>
+  <description>Free Dumb Bytes paperlike skin for the Maven site.</description>
+  <inceptionYear>2010</inceptionYear>
+</project>

Eat your own dog food by overriding the ancestor skin settings in W:\projects\maven-skins\maven-paper-skin\pom.xml:

   <inceptionYear>2010</inceptionYear>
+
+  <properties>
+    <skinGroupId>${project.groupId}</skinGroupId>
+    <skinArtifactId>${project.artifactId}</skinArtifactId>
+    <skinVersion>${project.version}</skinVersion>
+  </properties>
 </project>

And also override the <skin/> part of the ancestor W:\projects\maven-setup\src\site\site.xml with a simple W:\projects\maven-skins\maven-paper-skin\src\site\site.xml:

+<?xml version="1.0" encoding="UTF-8"?>
+
+<project xmlns="http://maven.apache.org/DECORATION/1.1.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/DECORATION/1.1.0
+                             http://maven.apache.org/xsd/decoration-1.1.0.xsd">
+  <skin>
+    <groupId>${skinGroupId}</groupId>
+    <artifactId>${skinArtifactId}</artifactId>
+    <version>${skinVersion}</version>
+  </skin>
+</project>

Activate the paperlike skin for all other sites with mvn install to be able to reference it in W:\projects\maven-setup\pom.xml:

   <properties>
-    <skinGroupId>org.apache.maven.skins</skinGroupId>
-    <skinArtifactId>maven-fluido-skin</skinArtifactId>
-    <skinVersion>1.2.1</skinVersion>
+    <skinGroupId>net.dev.freedumbytes.maven.skins</skinGroupId>
+    <skinArtifactId>maven-paper-skin</skinArtifactId>
+    <skinVersion>1.0-SNAPSHOT</skinVersion>
   </properties>
trickA.3.1.1.1. Customization

First customize the site banner and favicon with for example the following images:

  1. maven-skins/maven-paper-skin/src/main/resources/images/logos/shadowrun.png

  2. maven-skins/maven-paper-skin/src/main/resources/images/logos/shadowrun.jpg

Now reference them in W:\projects\maven-setup\src\site\site.xml:

   <bannerLeft>
-    <name>Free Dumb Bytes</name>
-    <href>http://dev.net</href>
+    <src>images/logos/shadowrun.png</src>
+    <alt>Free Dumb Bytes</alt>
+    <href>http://shadowrun.wikia.com</href>
   </bannerLeft>
   <body>
+    <head>
+      <link rel="shortcut icon" href="./images/logos/shadowrun.jpg" />
+    </head>
+
     <menu name="Free Dumb Bytes" inherit="top">

But before making the custom changes to the site template start out by extracting the doxia-sitetools siterenderer resources of version 1.2 with:

cd /d W:\projects
svn export ^
    http://svn.apache.org/repos/asf/maven/doxia/doxia-sitetools/tags/doxia-sitetools-1.2 ^
    doxia-sitetools-1.2

Copy the resources into project maven-skins:

cd doxia-sitetools-1.2\doxia-site-renderer\src\main\resources
cd org\apache\maven\doxia\siterenderer\resources
mkdir W:\projects\maven-skins\maven-paper-skin\src\main\resources\META-INF\maven
copy default-site.vm ^
     ...\maven-paper-skin\src\main\resources\META-INF\maven\site.vm
xcopy /S /I css ^
     W:\projects\maven-skins\maven-paper-skin\src\main\resources\css
xcopy /S /I images ^
     W:\projects\maven-skins\maven-paper-skin\src\main\resources\images

Commit those resource files:

  1. maven-skins/maven-paper-skin/src/main/resources/META-INF/maven/site.vm

  2. maven-skins/maven-paper-skin/src/main/resources/css/maven-base.css

  3. maven-skins/maven-paper-skin/src/main/resources/css/print.css

  4. maven-skins/maven-paper-skin/src/main/resources/images/collapsed.gif

  5. maven-skins/maven-paper-skin/src/main/resources/images/expanded.gif

  6. maven-skins/maven-paper-skin/src/main/resources/images/logos/build-by-maven-black.png

  7. maven-skins/maven-paper-skin/src/main/resources/images/logos/build-by-maven-white.png

  8. maven-skins/maven-paper-skin/src/main/resources/images/logos/maven-feather.png

Create a Fixed Header & Footer Layout:

  1. maven-skins/maven-paper-skin/src/main/resources/css/maven-base.css

  2. maven-skins/maven-paper-skin/src/main/resources/css/maven-theme.css

  3. maven-skins/maven-paper-skin/src/main/resources/css/print.css

  4. maven-skins/maven-paper-skin/src/main/resources/images/gradient-header.png

  5. maven-skins/maven-paper-skin/src/main/resources/images/gradient-footer.png

  6. maven-skins/maven-paper-skin/src/main/resources/images/paper.jpg

  7. maven-skins/maven-paper-skin/src/main/resources/images/logos/hacker.png

  8. maven-skins/maven-paper-skin/src/main/resources/js/css-browser-selector.js

  9. maven-skins/maven-paper-skin/src/main/resources/META-INF/maven/site.vm

Since the banner logo and the favicon are now set in maven-theme.css and site.vm remove the references in W:\projects\maven-setup\src\site\site.xml:

-  <bannerLeft>
-    <src>images/logos/shadowrun.png</src>
-    <alt>Free Dumb Bytes</alt>
-    <href>http://shadowrun.wikia.com</href>
-   </bannerLeft>
   <body>
-    <head>
-      <link rel="shortcut icon" href="./images/logos/shadowrun.jpg" />
-    </head>
-
     <menu name="Free Dumb Bytes" inherit="top">

Create a parchment like menu with Liquid Round Corners:

  1. maven-skins/maven-paper-skin/src/main/resources/css/maven-base.css

  2. maven-skins/maven-paper-skin/src/main/resources/css/maven-theme.css

  3. maven-skins/maven-paper-skin/src/main/resources/images/parchment.gif

  4. maven-skins/maven-paper-skin/src/main/resources/images/parchment-left-right-tearoff.gif

  5. maven-skins/maven-paper-skin/src/main/resources/images/parchment-top-bottom-tearoff.gif

  6. maven-skins/maven-paper-skin/src/main/resources/META-INF/maven/site.vm

Reclaim the empty space below the menu:

Index: maven-skins/maven-paper-skin/src/main/resources/css/maven-base.css
=========================================================================
 table {
   padding:0px;
-  width: 100%;
+  min-width: 70%;
   margin-left: -2px;
   margin-right: -2px;
 }
 #leftColumn {
-  width: 280px;
-  float:left;
-  overflow: auto;
+  float: right;
+  overflow: hidden;
 }
 #bodyColumn {
-  margin-right: 1.5em;
-  margin-left: 300px;
+  margin: 0px;
+  padding: 5px;
 }
Index: maven-skins/maven-paper-skin/src/main/resources/css/maven-theme.css
==========================================================================
 #leftColumn {
-  margin: 10px 0 0 5px;
-  padding-bottom: 3px; /* IE-9 scrollbar-fix */
+  margin: 0px;
+  padding: 5px;
+  position: relative;
+  z-index:999;
 }

Activate the changes with mvn install and verify them with mvn site in your browser at file:///W:/projects/maven-skins/maven-paper-skin/target/site/index.html.

Release 1.0 with:

mvn -Dusername=jjasper -Dpassword=password release:prepare
mvn -Dusername=jjasper -Dpassword=password release:perform

trickA.3.1.2. Custom Fluido Skin

To add some custom imagery repackage the Apache Maven Fluido Skin.

Define a new module maven-fluido-skin in W:\projects\maven-skins\pom.xml:

   </distributionManagement>
 
   <modules>
     <module>maven-paper-skin</module>
+    <module>maven-fluido-skin</module>
   </modules>
 </project>

Supply the new module W:\projects\maven-skins\maven-fluido-skin\pom.xml:

+<?xml version="1.0" encoding="UTF-8"?>
+
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
+                             http://maven.apache.org/maven-v4_0_0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <parent>
+    <groupId>net.dev.freedumbytes.maven.skins</groupId>
+    <artifactId>maven-skins</artifactId>
+    <version>1.1-SNAPSHOT</version>
+  </parent>
+  <artifactId>maven-fluido-skin</artifactId>
+  <packaging>jar</packaging>
+
+  <name>Free Dumb Bytes Fluido Skin</name>
+  <description>Free Dumb Bytes repackaged Fluido skin for the Maven site.</description>
+  <inceptionYear>2012</inceptionYear>
+  <properties>
+    <skinGroupId>${project.groupId}</skinGroupId>
+    <skinArtifactId>${project.artifactId}</skinArtifactId>
+    <skinVersion>${project.version}</skinVersion>
+  </properties>
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-dependency-plugin</artifactId>
+        <executions>
+          <execution>
+            <id>unpack-fluido-skin-stuff</id>
+            <phase>generate-resources</phase>
+            <goals>
+              <goal>unpack</goal>
+            </goals>
+            <configuration>
+              <artifactItems>
+                <artifactItem>
+                  <groupId>org.apache.maven.skins</groupId>
+                  <artifactId>maven-fluido-skin</artifactId>
+                  <version>1.2.1</version>
+                  <overWrite>true</overWrite>
+                  <outputDirectory>${project.build.outputDirectory}</outputDirectory>
+                </artifactItem>
+              </artifactItems>
+              <excludes>
+                **/MANIFEST.MF,
+                **/META-INF/maven/org.apache.maven.skins/maven-fluido-skin/pom.xml,
+                **/META-INF/maven/org.apache.maven.skins/maven-fluido-skin/pom.properties,
+                **/META-INF/maven/org.apache.maven.skins/**,
+              </excludes>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
+    </plugins>
+  </build>
+</project>

Fix Plugin execution not covered by lifecycle configuration of M2E when importing module into Eclipse (see also Section 15.1.5.5.1, “Maven workspace integration approach”) with:

   <build>
+    <pluginManagement>
+      <plugins>
+        <plugin>
+          <groupId>org.eclipse.m2e</groupId>
+          <artifactId>lifecycle-mapping</artifactId>
+          <version>1.0.0</version>
+          <configuration>
+            <lifecycleMappingMetadata>
+              <pluginExecutions>
+                <pluginExecution>
+                  <pluginExecutionFilter>
+                    <groupId>org.apache.maven.plugins</groupId>
+                    <artifactId>maven-dependency-plugin</artifactId>
+                    <versionRange>[2.4,)</versionRange>
+                    <goals>
+                      <goal>unpack</goal>
+                    </goals>
+                  </pluginExecutionFilter>
+                  <action>
+                    <ignore />
+                  </action>
+                </pluginExecution>
+              </pluginExecutions>
+            </lifecycleMappingMetadata>
+          </configuration>
+        </plugin>
+      </plugins>
+    </pluginManagement>
+
     <plugins>
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-dependency-plugin</artifactId>

Supply the site banners, powered by and favicon with for example the following images:

  1. maven-skins/maven-fluido-skin/src/main/resources/images/logos/Bocca-della-Verita.png

  2. maven-skins/maven-fluido-skin/src/main/resources/images/logos/hacker.png

  3. maven-skins/maven-fluido-skin/src/main/resources/images/logos/Janus.png

  4. maven-skins/maven-fluido-skin/src/main/resources/images/logos/shadowrun.jpg

Now reference them in W:\projects\maven-setup\src\site\site.xml:

   <bannerLeft>
-    <name>Free Dumb Bytes</name>
-    <href>http://dev.net</href>
+    <name>Bocca della Verità</name>
+    <src>images/logos/Bocca-della-Verita.png</src>
+    <href>http://en.wikipedia.org/wiki/Bocca_della_Verita</href>
+    <width>138</width>
+    <height>125</height>
   </bannerLeft>
+  <bannerRight>
+    <name>Janus</name>
+    <src>images/logos/Janus.png</src>
+    <href>http://en.wikipedia.org/wiki/Janus</href>
+    <width>116</width>
+    <height>125</height>
+  </bannerRight>
   <publishDate position="left" format="yyyy-MM-dd HH:mm:ss z" />
   <version position="left" />
+  <poweredBy>
+    <logo name="Free Dumb Bytes"
+          href="http://dev.net"
+          img="./images/logos/hacker.png"
+          width="80" height="15" />
+  </poweredBy>
   <body>
+    <head>
+      <link rel="shortcut icon" href="./images/logos/shadowrun.jpg" />
+    </head>
+
     <menu name="Free Dumb Bytes" inherit="top">

To customize the site layout get a copy of W:\projects\maven-skins\maven-fluido-skin\target\classes\META-INF\maven\site.vm in W:\projects\maven-skins\maven-fluido-skin\src\main\resources\META-INF\maven. And tweak for example the banner to always display the project name.

Release 1.1 with:

mvn -Dusername=jjasper -Dpassword=password release:prepare
mvn -Dusername=jjasper -Dpassword=password release:perform

Activate the repackaged skin for all other sites in W:\projects\maven-setup\pom.xml:

   </distributionManagement>
 
   <properties>
-    <skinGroupId>org.apache.maven.skins</skinGroupId>
+    <skinGroupId>net.dev.freedumbytes.maven.skins</skinGroupId>
     <skinArtifactId>maven-fluido-skin</skinArtifactId>
-    <skinVersion>1.2.1</skinVersion>
+    <skinVersion>1.1</skinVersion>
   </properties>

trickA.3.2. Quality Assurance Sandbox

Lets setup a base structure, for QA Sandbox code to come, with the following JIRA project:

  • QA Sandbox [QASNDBX]: QA Sandbox sample code. (for the source see Appendix D, Source)

    With the following components:

    1. sandbox: Code sandbox.

    and versions:

    • 1.0 - QA Plugins config.

Start a new Git repository qa-sandbox by calling http://dev.net/git-repo?pn=qa-sandbox&pd=QA+Sandbox+sample+code&a=create direct or through the GitWeb user interface.

Clone this remote repository with the following command git-clone jjasper qa-sandbox.

Create the QA Sandbox project, with sample code for FindBugs, PMD and Checkstyle to eliminate duplicate checks, in W:\projects\qa-sandbox\pom.xml:

+<?xml version="1.0" encoding="UTF-8"?>
+
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
+                             http://maven.apache.org/maven-v4_0_0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <parent>
+    <groupId>net.dev.freedumbytes.maven</groupId>
+    <artifactId>setup</artifactId>
+    <version>2.1-SNAPSHOT</version>
+  </parent>
+  <artifactId>qa-sandbox</artifactId>
+  <version>1.0-SNAPSHOT</version>
+  <name>Free Dumb Bytes Quality Assurance Sandbox</name>
+  <description>Free Dumb Bytes sample code for FindBugs, PMD and Checkstyle 
                to eliminate duplicate checks.</description>
+  <inceptionYear>2010</inceptionYear>
+  <developers>
+    <developer>
+      <id>jjasper</id>
+      <name>Jene Jasper</name>
+      <email>jjasper@dev.java.net</email>
+      <organization>Free Dumb Bytes</organization>
+      <organizationUrl>http://dev.net</organizationUrl>
+      <roles>
+        <role>developer</role>
+      </roles>
+      <timezone>+1</timezone>
+    </developer>
+  </developers>
+
+  <contributors />
+  <scm>
+    <developerConnection>scm:git:http://dev.net/git-repo/qa-sandbox.git</developerConnection>
+    <url>http://dev.net/fisheye/browse/qa-sandbox</url>
+  </scm>
+  <distributionManagement>
+    <site>
+      <id>mvn-sites</id>
+      <name>Maven Documentation Sites</nam