Development Production Line

The Short Story

Jene Jasper

Published 30 January 2017

3.2-beta Edition

trick

While every precaution has been taken in the preparation of this installation manual, the publisher and author assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein.

This work is licensed under a Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License.

To get an idea of the Development Production Line take a look at the following Application Integration overview and Maven vs SonarQube Quality Assurance reports comparison.


Table of Contents

Chapter 1. Operating System

1.1. Windows

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

1.1.1. Resources

  • Leaving Microsoft to Change the World.

  • Microsoft Security Advisories are a supplement to the Microsoft Security Bulletins. They address security changes that may not require a security bulletin but that may still affect customers' overall security.

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

  • Everything You Need To Know About the Blue Screen of Death. How to configure Windows to create MiniDump files on BSOD. BlueScreenView scans all your minidump files created during 'blue screen of death' crashes, and displays the information about all crashes in one table.

  • MemTest86 is the original, free, stand alone memory testing software for x86 computers. MemTest86 boots from a USB flash drive or CD and tests the RAM in your computer for faults using a series of comprehensive algorithms and test patterns.

  • Drivers can be selected for verification by using the Verifier Command Line, or by using Driver Verifier Manager.

  • LessMSI is a tool to view and extract the contents of a Windows Installer (.msi) file..

  • 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 Visual C++ Redistributable Packages install runtime components that are required to run C++ applications built with Visual Studio.

  • Quick fix for disappearing system tray icons.

  • Kernel sockets leak on a multiprocessor computer that is running Windows Server 2008 R2 or Windows 7 resulting in JVM_Bind java.net.SocketException: No buffer space available (maximum connections reached?)

  • Windows 7 FOUND.000 File folder.

  • Snipping Tool to capture a screen shot, or snip, of any object on your screen, and then annotate, save, or share the image.

    Tip

    To capture context menus first start a New snip but cancel with Esc. Now open the desired menu and submenus followed by Ctrl+PrintScreen to restart capturing (see for example Figure 15.7, “Eclipse Mylyn Task List view”).

  • IrfanView is a very fast, small, compact and innovative graphic viewer for Windows [version 4.40].

  • Paint.NET is just about perfect for the graphic design needs of a non-graphic-designer when you need to crop, cut, or otherwise edit an image and Windows' built-in Paint isn't quite enough [version 4.0.6].

  • GIMP is the GNU Image Manipulation Program. It is a freely distributed piece of software for such tasks as photo retouching, image composition and image authoring. It works on many operating systems, in many languages [version 2.8.14].

  • Inkscape is professional quality vector graphics software for creating a wide variety of graphics such as illustrations, icons, logos, diagrams, maps and web graphics. Inkscape uses the W3C open standard SVG (Scalable Vector Graphics) as its native format [version 0.91].

  • VLC (VideoLAN Client) is a free and open source cross-platform multimedia player and framework that plays most multimedia files as well as DVDs, Audio CDs, VCDs, and various streaming protocols [version 2.2.2].

  • security.nl.

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

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

1.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. Make sure the taskbar is unlocked (Lock the taskbar is unchecked), otherwise these menu options won't be available.

1.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 16.05].

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

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

Important

In case of the following errors:

  • [SC] DeleteService FAILED 1072: The specified service has been marked for deletion.

  • CreateService failed - The specified service has been marked for deletion. (0x430).

just Close Process Explorer and/or any services.msc console.

If a service still hangs with the following error The service is starting or stopping. Please try again later. see Kill stuck Windows service using sc queryex and taskkill.

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

1.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 33.6.2015.18].

Run this .exe file to install WinPatrol in P:\dev\apps\windows\win-patrol.

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

1.1.9. Windows Languages

Go to Start MenuControl PanelRegion and Language:

  • Formats: English (United States):

    • Short date: yyyy-MM-dd.

    • Long date: dddd, dd MMMM, yyyy.

    • Short time: HH:mm.

    • Long time: HH:mm:ss.

    • First day of week: Monday.

    • Additional settings… Currency symbol: .

  • Current location: United States.

  • Keyboards and Languages:

    • Change keyboards… Default input language: English (United States) - US.

    • Install/uninstall languages… Choose a display language: English.

  • Administrative:

    • Copy settings… to Welcome sceen and system accounts and New user accounts.

    • Change system locale… to English (United States).

1.1.10. Windows Disks

Go to Start MenuComputerManageStorageDisk Management and right click on new disk to:

  • Initialize Disk (GPT).

  • New Simple Volume and click Next (twice).

  • Assign the following drive letter: K and click Next.

  • Format this volume with the following settings: Volume Label Knowledge and click Next and Finish.

1.1.11. Windows Mouse and Keyboard

Microsoft Garage Mouse Without Borders is an immensely useful tool. It might come as something of a surprise that it is a tool associated with Microsoft, and even more of a surprise that it has been kept a secret. Mouse Without Borders is a product that makes you the captain of your computer fleet by allowing you to control up to four computers from a single mouse and keyboard. This means that with Mouse without Borders you can copy text or drag and drop files across computers.

ShareMouse lets you share your mouse and keyboard with multiple networked computers.

1.1.12. 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 (Forum for latest offline installer): avast_free_antivirus_setup_offline.exe [version 12.32280].

Run this .exe file for Customize installation of Avast in P:\dev\apps\antivirus\avast. Optionally uncheck the following features: Antispam, Secure DNS, Firewall, Sandbox, Software Updater, Browser Cleanup, Rescue Disk, Home Network Security, Security browser extension (a web reputation browser extension), SafeZone Browser, Desktop gadget, SafePrice browser extension, SecureLine VPN, Passwords and Cleanup.

Disable WebRep and Community settings with Open Avast user interfaceSettingsGeneral:

  • disable Participate in the Avast community.

  • disable Enable reputation services.

  • disable Enable DeepScreen since 12.1.2272 CyberCapture against zero-second attacks.

  • disable Enable Hardened mode.

  • disable Enable Avast email signature.

  • Sounds: disable Use voiceover sounds (when available).

  • Privacy: disable Participate in the Avast community and/or disable Participate in data sharing to Opt-out.

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

Note

See also Apache James James.Mailet: RemoteDelivery issue.

1.1.12.1. Resources

1.1.13. 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 from the Quick Launch Toolbar configure the following settings by clicking Alt+Space and selecting Properties 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 or 380 x Height 9999 and Window Size Width 130 or 380 x Height 83 or 125. Click Ok.

To quickly repeat any previously entered command use the and arrow keys and use the F7 key to view a history of all the commands that have been entered in that Command Processor.

1.1.13.1. Elevated Command Prompt

An elevated command prompt is a command prompt that you run with administrator privileges.

Create for example a another shortcut for the Command Proccessor in the Quick Launch Toolbar. Right click on this shortcut and select Properties:

  • Select Advanced to Run as administrator.

  • And for example Change Icon… and Browse… %windir%\system32\UserAccountControlSettings.exe to the User Account Control (UAC) icon.

1.1.13.2. User Account Control Consent Prompt

The consent prompt notification is presented when a user attempts to perform a task that requires a user's administrative access token. To disable those annoying prompts for administrators go to Start MenuControl PanelSystem and SecurityAdministrative ToolsLocal Security Policy or run secpol.msc. Select Security SettingsLocal PoliciesSecurity OptionsUser Account Control: Behavior of the elevation prompt for administrators in Admin Approval Mode and switch from Prompt for consent for non-Windows binaries to Elevate without prompting. Now it is possible to run the elevated command prompt without having to consent every time.

1.1.13.3. Edit the Hosts File

When editing the hosts file results in the following error You don't have permission to save in this location open an elevated command prompt and run notepad %windir%\system32\drivers\etc\hosts.

1.1.13.4. Batch files

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

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

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

1.1.14.2. Service Wrapper

WinSW 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 +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.18], 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!.

1.1.14.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 fisheye
net start jira
net start nexus
net start sonarqube
net start tomcat
net start payara

REM pause 10 seconds
ping -n 10 127.0.0.1  > NUL

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

net stop payara
net stop tomcat
net stop sonarqube
net stop nexus
net stop jira
net stop fisheye
net stop mysqlmaster
net stop james

REM pause 10 seconds
ping -n 10 127.0.0.1  > NUL

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

1.1.16. Text editor

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

1.1.16.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.8.2.Installer.exe [version 6.8.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.

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

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

1.1.17.1. WinRAR

WinRAR is a powerful archive manager.

Download the binary: winrar-x64-521.exe [version 5.21].

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.

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

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

1.1.18. GnuWin32

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

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

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

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

Sample command patch -i viewvc-1.1.5.patch.diff -p 0 --verbose (add the option --dry-run if you want to check the patch first). You can revert the patch by adding the option -R.

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.

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

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

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

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

1.1.19.1. KDiff3

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

Download the binary: KDiff3-32bit-Setup_0.9.98-3.exe [version 0.9.98].

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

1.1.19.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.14.0-Setup.exe [version 2.14.0].

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.

Tip

If the WinMerge Windows Explorer context menu conflicts with the New menu usage then disable it by selecting EditOptions…Shell Integration and uncheck Add to context menu.

1.1.20. Secure Shell

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

1.1.20.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.65].

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

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

1.1.21. The Best Application Launcher for Windows

Do you still launch applications by pressing the Windows key and searching for your app? That's a serviceable way to get your apps up and running, but it's pretty limited. If you've never used an app launcher, now's the time to try one: they're faster and more powerful than any built-in search system, and they can do a lot more than just launch apps. Here's why you should be using one (and everything you can do with it).

Launchy is a free cross-platform utility designed to help you forget about your start menu, the icons on your desktop, and even your file manager.

Download the binary: Launchy2.5.exe [version 2.5].

Run this .exe file to install WinSCP in P:\dev\apps\windows\launchy.

Additionally install required plugins sucha as putty-launchy-plugin [version 2.4].

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

1.1.22.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: winscp575setup.exe [version 5.7.5].

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

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

1.1.23. 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.38.msi [version 2.38].

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

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

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

How to Analyse Bugcheck and Process Crash Dumps.

1.1.25. Viewers

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

1.1.25.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 up to KB2965209].

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

1.1.25.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 SP3 up to KB3055054].

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

1.1.25.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 SP1 up to KB3054840].

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

1.1.25.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: FoxitReader720.0722_prom_enu_Setup.exe [version 7.2.0.0722].

Run this .exe file to custom install Foxit Reader (and optionally the Plug-ins: Word, PPT and Excel) in P:\dev\apps\editor\foxit.

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

1.1.25.5. Irfanview

IrfanView is a very fast, small, compact and innovative graphic viewer for Windows.

Download the binary: iview438_setup.exe [version 4.40].

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

Download the binary: irfanview_plugins_438_setup.exe [version 4.40].

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

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

1.1.26.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: rcsetup152.exe [version 1.52.1086].

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

1.1.26.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: ccsetup509.exe [version 5.09.5343].

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

1.1.26.3. Defraggler

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

Download the binary: dfsetup219.exe [version 2.19.982].

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

1.1.26.4. Speccy

Speccy is an advanced System Information tool for your machine.

Download the binary: spsetup128.exe [version 1.28.709].

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

1.1.26.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: reshacker_setup.exe [version 4.2.5].

Extract the .zip file to P:\dev\apps\windows\resource-hacker.

Chapter 2. Browser

2.1. Firefox

Firefox the Web browser from Mozilla.

2.1.1. Resources

  • Download a Firefox version that speaks your language. Keeping your plugins up to date helps Firefox run safely and smoothly. Skip Firefox's Add-On Compatibility Check with This Small Extension.

  • Waterfox is a Faster, 64-Bit Optimized Version of Firefox for Windows PCs. Firefox 64-Bit Now Available for Windows with Improved Performance. Users will notice that NPAPI Plugins in Firefox will not work in this 64-bit version.

  • How to stop Firefox from making automatic connections. OpenH264 Now in Firefox.

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

  • LifeHacker tips & downloads for getting things done.

  • The POODLE SSL vulnerability: disabling SSL v3 in your Azure Virtual Machines and Web Roles. POODLE Vulnerability Affects TLS 1.0, TLS 1.1.

  • Mozilla Improves Firefox's Certificates Visibility and Mozilla To Remove Favicons From Firefox URL Bar.

  • Add-ons extend Firefox, letting you personalize your browsing experience (see also The Best Firefox Addons):

    • FT DeepDark is a smooth dark theme for Firefox.

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

    • QuickJava allows quick enable and disable of Java, Javascript, Cookies, Image Animations, Flash, Silverlight, Images, Stylesheets and Proxy from the Statusbar and/or Toolbar.

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

      Note

      Uncheck Yes, install McAfee Security Scan Plus - optional before first download.

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

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

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

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

    • Remove Cookies for Site a very simple extension to remove all the cookies of currently opened site.

    • Session Manager saves and restores the state of all or some windows - either when you want it or automatically at startup and after crashes. It can also automatically save the state of open windows individually.

    • The Tab Groups (Panorama) feature will be removed from Firefox in version 45. Tab Groups are an easy way to organize a lot of tabs. You can visually group related tabs, switch between groups, and quickly search through all of your tabs to switch to a specific one.

    • Redirector is a browser add-on for Firefox, Chrome and Opera. The add-on lets you create redirects for specific webpages, e.g. always redirect http://bing.com to http://google.com. Don't you hate it when a website automatically redirects you to a localized version?

  • Disabling Flash on Chrome and Firefox.

  • The about:about page is an index of Firefox's about pages.The about:support page provides information you might need to troubleshoot problems with Firefox. About:config is the about: page most geeks have heard of. It provides access to all sorts of internal Firefox options that aren't exposed in the user interface - it's the go-to place for tweaking Firefox.

2.1.2. Firefox installation guide

Download the Win32 or Win64 binary: Firefox Setup 45.0.2.exe [version 45.0.2] (How to tell if Firefox is 32-bit or 64-bit).

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. To reactivate the menu bar type Alt and check ViewToolbarsMenu Bar.

Tip

http://www.google.com/ncr stops google.com from redirecting to local country or language version of Google.

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

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

security.tls.version.(min / max / fallback-limit)

Set to 3 to make TLS 1.2 is the minimum required / maximum supported encryption protocol (verify with POODLE Test).

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

browser.tabs.onTop

Disable this preference to put the tabs back on bottom like they used to be.

browser.urlbar.trimURLs

Disable url trimming in Firefox so that the http protocol is shown on all tabs again.

browser.urlbar.formatting.enabled

Disable url formatting so that the url is displayed in one color.

network.prefetch-next

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

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

2.2. Safari

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

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

2.2.2. Safari installation guide

Download or download.cnet.com the Win32 binary: SafariSetup.exe [version 5.1.7].

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

2.3. Chrome

Chrome runs websites and applications with lightning speed.

2.3.1. Resources

  • Download a Chrome version.

  • Chrome Cleanup Tool application will scan and remove software that may cause problems with Chrome, such as crashes, unusual startup pages or toolbars, unexpected ads you can't get rid of, or otherwise changing your browsing experience.

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

  • POODLE Disabling SSLv3 Support in Browsers.

  • Quickly Save Tab Sessions in Chrome Without Installing Extensions.

2.3.2. Chrome installation guide

Download the Win32 binary: ChromeSetup.exe for the Google Chrome Web Browser only [version 49.0.2623.112]. Or as an alternative download the standalone installer ChromeStandaloneSetup.exe (see also Disabling SSLv3 Support in the above mentioned Resources).

Run one of those .exe file to install Chrome.

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

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

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

Warning

The extra junction for the browser itself is now reverted because it caused The application has failed to start because its side-by-side configuration is incorrect. for new_chrome.exe after the update to 49.0.2623.110. Reinstall resulted in the following recurring error An error occurred while checking for updates: Update check failed to start (error code 1: 0x80004005). when viewing, in the top right, the Chrome menu HelpAbout Google Chrome version information (Chrome will check for updates when you're on this page).

rem Note: on 32-bit use %PROGRAMFILES%
mkdir P:\dev\apps\browser\chrome
mkdir "%PROGRAMFILES(X86)%\Google"

junction "%PROGRAMFILES(X86)%\Google\Chrome" P:\dev\apps\browser\chrome
junction -s "%PROGRAMFILES(X86)%\Google"

To reopen the prior pages/tabs edit, in the top right, Chrome menu SettingsOn Startup and select Continue where you left off.

Chapter 3. Programming Languages

3.1. Java 2 Platform

Java Platform, Standard Edition (Java SE) lets you develop and deploy Java applications on desktops and servers, as well as in today's demanding embedded environments. Java offers the rich user interface, performance, versatility, portability, and security that today's applications require.

3.1.1. Resources

3.1.2. JDK installation guide

Download the Win32 binary: jdk-8u121-windows-i586.exe [version 1.8.0_121] for the use with for example Firefox and the Win64 binary: jdk-8u121-windows-x64.exe for development purposes.

Run the 32-bit .exe file to install the JDK Development Tools with Change… into P:\dev\apps\prg\java\jdk1.8.0_121. After the JDK is installed Change… the JRE Destination Folder into P:\dev\apps\prg\java\jre1.8.0_121.

Run the 64-bit .exe file to install the JDK Development Tools with Change… into P:\dev\apps\prg\java-x64\jdk1.8.0_121. After the JDK is installed Change… the JRE Destination Folder into P:\dev\apps\prg\java-x64\jre1.8.0_121.

Note

It seems Java SE 8 Update 60 doesn't have Public JRE installation included.

trickPress +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-x64\jdk1.8.0_121.

Verify the installation with java -version.

3.1.3. Thoughts on Java SE, Java Security and Usability

When building inter-connected applications, developers frequently interact with TLS-enabled protocols like HTTPS:

When working with https URLs that cause an error SSLHandshakeException: Received fatal alert: handshake_failure in Java but work in the browser, you might want to install the files, from the above mentioned JCE, local_policy.jar and US_export_policy.jar in:

  • %JRE_HOME%\lib\security and/or

  • %JAVA_HOME%\jre\lib\security.

3.1.3.1. Standard Edition Tools Reference

Java Platform, Standard Edition Tools Reference describes for example the general purpose options that are specific to the Java HotSpot Virtual Machine such as -Xrs, which reduces the use of operating system signals by the JVM.

Shutdown hooks enable orderly shutdown of a Java application by running user cleanup code (such as closing database connections) at shutdown, even if the JVM terminates abruptly.

The JVM watches for console control events to implement shutdown hooks for unexpected termination. Specifically, the JVM registers a console control handler that begins shutdown-hook processing and returns TRUE for CTRL_C_EVENT, CTRL_CLOSE_EVENT, CTRL_LOGOFF_EVENT, and CTRL_SHUTDOWN_EVENT.

The JVM uses a similar mechanism to implement the feature of dumping thread stacks for debugging purposes. The JVM uses CTRL_BREAK_EVENT to perform thread dumps.

If the JVM is run as a service (for example, as a servlet engine for a web server), then it can receive CTRL_LOGOFF_EVENT but should not initiate shutdown because the operating system will not actually terminate the process. To avoid possible interference such as this, the -Xrs option can be used. When the -Xrs option is used, the JVM does not install a console control handler, implying that it does not watch for or process CTRL_C_EVENT, CTRL_CLOSE_EVENT, CTRL_LOGOFF_EVENT, or CTRL_SHUTDOWN_EVENT.

Note

Testing Log off for user .\Tomcat under which the windows services, without the option -Xrs, are running, didn't result in the service stopping. Tested with services tomcat, jeeves and nexus.

There are two consequences of specifying -Xrs:

  • Ctrl+Break thread dumps are not available.

  • User code is responsible for causing shutdown hooks to run, for example, by calling System.exit() when the JVM is to be terminated.

3.2. Visual Studio C# and C++

Visual Studio Community is a free, fully-featured, and extensible IDE for creating modern applications for Windows, Android, and iOS, as well as web applications and cloud services. Multi-language support includes C#, Visual Basic, F#, C++, JavaScript, TypeScript, Python, and more. Visual Studio guides you as you write, debug, and test code — no matter what language you choose.

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

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

3.3.1. Resources

3.3.2. Python installation guide

Download the Win64 binary (MSI Installer): python-3.4.3.amd64.msi [version 3.4.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-3.4.3.

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

Verify the installation with python --version.

Download the Python for Windows Extensions Win64 binary: pywin32-219.win-amd64-py3.4.exe [version 219].

Run this .exe file to install the Windows extensions in P:\dev\apps\prg\python-3.4.3.

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

3.3.3.1. Setuptools installation guide

Download the install script ez_setup.py that will download the appropriate setuptools-x.x.x-pyx.x.egg to for example python P:\dev\tools\prg\python\ez_setup.py [version 18.3.1].

Run python P:\dev\tools\prg\python\ez_setup.py to install setuptools-18.3.1-py3.4.egg into P:\dev\apps\prg\python-3.4.3.

Note

In case of an upgrade of the setuptools delete the setuptools.pth and setuptools-x.x.x-pyx.x.egg from P:\dev\apps\prg\python-3.4.3\Lib\site-packages to avoid the following error message: zipimport.ZipImportError: bad local file header in …\lib\site-packages\setuptools-0.9.6-py3.3.egg.

Press +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 --version.

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

3.3.4.1. Pygments installation guide

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

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

3.4.1. Resources

3.4.2. Perl installation guide

Download the Win64 Binary (MSI Installer): ActivePerl-5.22.0.2200-MSWin32-x64-299195.msi [version 5.22.0.2200].

Note

In case of Perl usage in combination with Bugzilla and MySQL check availabitly of DBD-mysql.

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.22.0.2200 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 +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.22.0.2200 and reboot the server.

Verify the installation with perl -V.

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

To add alternative repositories such as Scraps of Perl run the following command ppm repo add bribes-de-perl http://www.bribes.org/perl/ppm64/.

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.

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

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

3.4.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 Win64 binary: ImageMagick-6.9.2-0-Q16-x64-dll.exe [version 6.9.2-0].

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

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

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

3.5. PHP

PHP is a widely-used general-purpose scripting language that is especially suited for Web development and can be embedded into HTML.

3.5.1. Resources

3.5.2. PHP installation guide

Download the archive: php-5.6.13-Win32-VC11-x64.zip [version 5.6.13].

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

Note

Navigate into this directory and rename the file php.ini-development or php.ini-production to php.ini.

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

The VC11 build requires to have the Microsoft Visual C++ 2012 Redistributable Package SP4 (x64) installed.

Verify the installation with php -v.

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

3.6.1. Resources

  • Download the latest release.

  • Upgrade checklist:

    • Related products: -.

    • References: -.

    • Integration configuration changes: -.

  • SWIG Documentation.

3.6.2. SWIG installation guide

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

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

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

Chapter 4. Build Tool

4.1. Ant

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

4.1.1. Resources

4.1.2. Ant installation guide

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

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

trickPress +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.9.6.

Verify the installation with ant -version.

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

4.2.1. Resources

4.2.2. Maven installation guide

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

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

trickPress +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.3.9.

The location of your local repository 1 can be changed in the Maven configuration file P:\dev\apps\build\apache-maven-3.3.9\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: ${user.home}/.m2/repository
  <localRepository>/path/to/local/repo</localRepository>
  -->
  <localRepository>C:/dev/data/repo/maven/local</localRepository>trick1

trickPress +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 -Xmx512m -Xms128m.

Note

Since JDK 8 JEP 122: Remove the Permanent Generation from the Hotspot JVM and thus the need to tune the size of the permanent generation with for example: -XX:MaxPermSize=192m.

Tip

Should the Surefire Plugin fail to run with one of the following errors:

  • Error occurred during initialization of VM Could not reserve enough space for object heap Could not create the Java virtual machine.

  • RuntimeException: The forked VM terminated without saying properly goodbye. VM crash or System.exit called ?

just temporarily overrule the maximum Java heap size setting with set _JAVA_OPTIONS=-Xmx256m, which will be notified with this message Picked up _JAVA_OPTIONS: -Xmx256m (see also JAVA_TOOL_OPTIONS).

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 or mvn -v.

4.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.3.9\conf\settings.xml:

  <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_45</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-x64\jdk1.7.0_80</jdk.1.7.home>
        <!--jdk.1.7.home>P:\dev\apps\prg\java\jdk1.7.0_80</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>

        <jdk.1.8.home>P:\dev\apps\prg\java-x64\jdk1.8.0_121</jdk.1.8.home>
        <!--jdk.1.8.home>P:\dev\apps\prg\java\jdk1.8.0_121</jdk.1.8.home-->
        <jdk.1.8.jvm>${jdk.1.8.home}\bin\java.exe</jdk.1.8.jvm>
        <jdk.1.8.javac>${jdk.1.8.home}\bin\javac.exe</jdk.1.8.javac>
        <jdk.1.8.javadoc>${jdk.1.8.home}\bin\javadoc.exe</jdk.1.8.javadoc>
      </properties>
    </profile>
  </profiles>

4.2.3.1. Toolchains

In our days it becomes more and more important to be able to use different JDK to be used by Maven itself and which is used to compile/test your production code. This concept is know under the name Toolchains which is unfortunately not very well-known.

Also configure Maven Toolchains with the locations of all available java compilers in the Maven configuration file P:\dev\apps\build\apache-maven-3.3.9\conf\toolchains.xml:

<?xml version="1.0" encoding="UTF-8"?>
<toolchains xmlns="http://maven.apache.org/TOOLCHAINS/1.1.0" 
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://maven.apache.org/TOOLCHAINS/1.1.0 http://maven.apache.org/xsd/toolchains-1.1.0.xsd">
  <toolchain>
    <type>jdk</type>
    <provides>
      <version>1.3</version>
      <vendor>oracle</vendor>
    </provides>
    <configuration>
      <jdkHome>P:\dev\apps\prg\java\jdk1.3.1_20</jdkHome>
    </configuration>
  </toolchain>

  <toolchain>
    <type>jdk</type>
    <provides>
      <version>1.4</version>
      <vendor>oracle</vendor>
    </provides>
    <configuration>
      <jdkHome>P:\dev\apps\prg\java\jdk1.4.2_19</jdkHome>
    </configuration>
  </toolchain>
 
  <toolchain>
    <type>jdk</type>
    <provides>
      <version>1.5</version>
      <vendor>oracle</vendor>
    </provides>
    <configuration>
      <jdkHome>P:\dev\apps\prg\java\jdk1.5.0_22</jdkHome>
    </configuration>
  </toolchain>
 
  <toolchain>
    <type>jdk</type>
    <provides>
      <version>1.6</version>
      <vendor>oracle</vendor>
    </provides>
    <configuration>
      <jdkHome>P:\dev\apps\prg\java\jdk1.6.0_45</jdkHome>
    </configuration>
  </toolchain>
 
  <toolchain>
    <type>jdk</type>
    <provides>
      <version>1.7</version>
      <vendor>oracle</vendor>
    </provides>
    <configuration>
      <jdkHome>P:\dev\apps\prg\java-x64\jdk1.7.0_80</jdkHome>
    </configuration>
  </toolchain>
 
  <toolchain>
    <type>jdk</type>
    <provides>
      <version>1.8</version>
      <vendor>oracle</vendor>
    </provides>
    <configuration>
      <jdkHome>P:\dev\apps\prg\java-x64\jdk1.8.0_121</jdkHome>
    </configuration>
  </toolchain> 
</toolchains>

Important

At least the folder of all specified jdkHome locations needs to exist otherwise projects that are configured to use the toolchains plugin will have build failures: [ERROR] Failed to execute goal org.apache.maven.plugins:maven-toolchains-plugin:1.1:toolchain (default) on project base-pom: Misconfigured toolchains. Non-existing JDK home configuration at P:\dev\apps\prg\java\jdk1.3.1_20-testing-non-existiing-folder -> [Help 1].

4.2.4. Logging

Configure Maven to include the current date and time in the output in the Maven logging configuration file P:\dev\apps\build\apache-maven-3.3.9\conf\logging\simplelogger.properties:

 org.slf4j.simpleLogger.defaultLogLevel=info
-org.slf4j.simpleLogger.showDateTime=false
+org.slf4j.simpleLogger.showDateTime=true
+org.slf4j.simpleLogger.dateTimeFormat=yyyyMMdd HH:mm:ss.SSS
 org.slf4j.simpleLogger.showThreadName=false
 org.slf4j.simpleLogger.showLogName=false
 org.slf4j.simpleLogger.logFile=System.out
 org.slf4j.simpleLogger.levelInBrackets=true
 org.slf4j.simpleLogger.log.Sisu=info
 org.slf4j.simpleLogger.warnLevelString=WARNING

4.2.5. Repository cleanup

Instead of deleting the local repository completely remove (current) project artifacts with:

qa-sandbox>mvn build-helper:remove-project-artifact -Dbuildhelper.removeAll=false
[INFO] C:\dev\data\repo\maven\local\net\dev\freedumbytes\manual\maven\qa-sandbox\1.1-delta removed.

qa-sandbox>mvn build-helper:remove-project-artifact
[INFO] C:\dev\data\repo\maven\local\net\dev\freedumbytes\manual\maven\qa-sandbox removed.

To delete or refresh project dependencies from the local repository run:

qa-sandbox>mvn dependency:purge-local-repository [-DreResolve=false]

4.2.6. Password Encryption

Maven 2.1.0+ now supports server password encryption.

Warning

maven-settings-decoder lets you decrypt these passwords as long as you have access to both the settings.xml file and the settings-security.xml file. To use it download the compiled distributable or build it from source (using gradle, because of irony).

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.3.9\conf\settings.xml:

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

Chapter 5. Documentation

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

5.1.1. Resources

5.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-6_4_0-setup-nojvm.exe [version 6.4.0].

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

5.1.3. XML Editor customization

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.

To customize the editor GUI, for example by adding the SelectLink menu items 1-5 next to the navigation buttons, edit P:\dev\apps\editor\xmlmind\doc\gui\gui\DesktopApp.xxe_gui:

  <toolBar name="selectToolBar" helpId="selectToolBar">
    <action name="findElementAction" />
    <separator />
    <action name="goBackAction" />
    <action name="goForwardAction" />
    <separator />trick1
    <action name="selectAnchorAction" />trick2
    <action name="selectLinkAction" />trick3
    <action name="selectPreviousLinkAction" />trick4
    <action name="selectNextLinkAction" />trick5
  </toolBar>

trickTo activate this customization press +Break keys to open the Windows System Properties. Select Advanced system settingsEnvironment Variables and add a New system variable XXE_GUI pointing to file:///P:/dev/apps/editor/xmlmind/doc/gui/gui/DesktopApp.xxe_gui.

Note

The original DesktopApp.xxe_gui can be restored from P:\dev\apps\editor\xmlmind\bin\xxe.jar.

Chapter 6. Mail Server

6.1. Thunderbird

Reclaim your inbox with Mozilla's email application Thunderbird.

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

    • Lightning Calendar to organize your life — it's about time! Integrated by default with your Thunderbird.

    • TT DeepDark is a smooth dark theme for Thunderbird.

6.1.2. Thunderbird installation guide

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

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.

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

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

6.2.1. Resources

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

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

6.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.freedumbytes.dev.nettrick1

6.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.freedumbytes.dev.nettrick4</servername>
      </servernames>
      <usernames ignoreCase="true" enableAliases="true" enableForwarding="true"/>
      <inboxRepository>
         <repository destinationURL="file://var/mail/inboxes/" type="MAIL"/>
      </inboxRepository>
   </James>

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

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

6.2.3.4.1. PuTTY configuration

Run PuTTY and configure the following custom Session:

  • Host Name: mail.freedumbytes.dev.net.

  • Telnet.

  • Port: 4555.

  • ConnectionTelnetTelnet negotiation mode: Passive.

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

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

6.2.3.5.1. PuTTY configuration

Run PuTTY and configure the following custom Session:

  • Host Name: mail.freedumbytes.dev.net.

  • Telnet.

  • Port: 25.

  • ConnectionTelnetTelnet negotiation mode: Passive.

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

6.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.freedumbytes.dev.nettrick3</helloName>
         <connectiontimeout>120000</connectiontimeout>
      </handler>
   </pop3server>

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

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

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

  • /mail/inboxes/

  • /mail/error/

  • /mail/outgoing/

  • /mail/spam/

  • /mail/address-error/

  • /mail/relay-denied/

  • /nntp/groups

  • /nntp/temp

  • /nntp/articleid

  • /nntp/spool

  • /mail/spool/

  • /dbmail (2x)

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

6.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-5 in the service wrapper configuration file P:\dev\apps\mail\james-2.3.2\conf\wrapper.conf:

 …

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

 …

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

 …

# Wrapper Windows NT/2000/XP Service Properties
wrapper.ntservice.name=James 2.3.2jamestrick3
wrapper.ntservice.displayname=freedumbytes.dev.net Apache Jamestrick4
wrapper.ntservice.description=The Java Apache Mail Enterprise Server.trick5

Register the Apache James service with the command in an elevated command processor: %JAMES_HOME%\bin\Wrapper.exe -i %JAMES_HOME%\conf\wrapper.conf. Start Apache James with net start james.

Important

In case of a new jdk installation use an elevated command prompt just run net stop james and net start james.

6.2.4.1. Log On Windows user

For the same reason as Section 8.1.3.1, “Log On Windows user” launch the Service Management Console with services.msc. Right click on freedumbytes.dev.net Apache James and select PropertiesLog On to use This account .\Tomcat. After password conformation click Apply and restart the service.

Chapter 7. HTTP Server

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

7.1.1. Resources

7.1.2. Apache HTTP Server installation guide

Download the archive: httpd-2.4.16-win64-VC14.zip [version 2.4.16].

Extract this .zip file to P:\dev\apps\httpserver and rename P:\dev\apps\httpserver\Apache24 to P:\dev\apps\httpserver\apache-2.4.16.

The VC11 build requires to have the Microsoft Visual C++ 2015 Redistributable Package (x64) installed.

To use the custom installation location in P:\dev\apps\httpserver\apache-2.4.16 edit the configuration file P:\dev\apps\httpserver\apache-2.4.16\conf\httpd.conf:

ServerRoot "c:/Apache24P:/dev/apps/httpserver/apache-2.4.16"
 …
DocumentRoot "c:/Apache24P:/dev/apps/httpserver/apache-2.4.16/htdocs"
<Directory "c:/Apache24P:/dev/apps/httpserver/apache-2.4.16/htdocs">
 …
    ScriptAlias /cgi-bin/ "c:/Apache24
                          P:/dev/apps/httpserver/apache-2.4.16/cgi-bin/"
 …
#
# "c:/Apache24P:/dev/apps/httpserver/apache-2.4.16/cgi-bin" should be changed 
# to whatever your ScriptAliased
# CGI directory exists, if you have that configured.
#
<Directory "c:/Apache24P:/dev/apps/httpserver/apache-2.4.16/cgi-bin">

Configure and uncomment the following general information P:\dev\apps\httpserver\apache-2.4.16\conf\httpd.conf:

ServerAdmin admin@example.comhttp.admin@company.org
 …
ServerName www.example.comfreedumbytes.dev.net:80

trickPress +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.4.16 .

Verify the installation with httpd -v.

Tip

From the command line run httpd -t to run a syntax check on the changed config files.

7.1.3. Windows service

To restart automatically on Microsoft Windows listening on port 80 install the service with the command in an elevated command processor: httpd -k install -n "freedumbytes.dev.net Apache HTTP" (which will result in a service named freedumbytes.dev.netApacheHTTP) and start it with httpd -k start -n "freedumbytes.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 "freedumbytes.dev.net Apache HTTP" first (see also Section 1.1.5, “Task Manager replacement” in case of The specified service has been marked for deletion.).

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.

7.1.3.1. Log On Windows user

For the same reason as Section 8.1.3.1, “Log On Windows user” launch the Service Management Console with services.msc. Right click on freedumbytes.dev.net Apache HTTP and select PropertiesLog On to use This account .\Tomcat. After password conformation click Apply and restart the service.

7.1.4. Apache HTTP Server access

Require tests whether an authenticated user is authorized according to a particular authorization provider and the specified restrictions. Block Internet access 1 based on ips 2 in the two non default Directory elements of P:\dev\apps\httpserver\apache-2.4.16\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.4.16/htdocs"
<Directory "P:/dev/apps/httpserver/apache-2.4.16/htdocs">
     …

    #
    # Controls who can get stuff from this server.
    #
trick1    Require all granted
trick2    Include ../apache-conf/httpd-lan-access.conf
</Directory>

 …

#
# "P:/dev/apps/httpserver/apache-2.4.16/cgi-bin" should be changed to whatever
# your ScriptAliased CGI directory exists, if you have that configured.
#
<Directory "P:/dev/apps/httpserver/apache-2.4.16/cgi-bin">
    AllowOverride None
    Options None
trick1    Require all granted
trick2    Include ../apache-conf/httpd-lan-access.conf
</Directory>

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

<RequireAny>
  # Local area network partial IP rangetrick1
  Require ip 192.168.0

  Include ../apache-conf/httpd-localhost-access.conftrick2
</RequireAny>

Create P:\dev\apps\httpserver\apache-conf\httpd-localhost-access.conf to allow access from localhost:

<RequireAny>
  # Localhost
  Require ip 127.0.0.1
  Require ip ::1
</RequireAny>

7.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-freedumbytes.dev.net 
  goto addUser

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

goto end
  
:addUser
htpasswd P:\dev\data\httpserver\security\http-users-freedumbytes.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-freedumbytes.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-freedumbytes.dev.net:

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

7.1.4.2. Realm

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

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

Add as an extra requirement 1 the freedumbytes realm with basic authentication 2 to P:\dev\apps\httpserver\apache-2.4.16\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.4.16/htdocs"
<Directory "P:/dev/apps/httpserver/apache-2.4.16/htdocs">
     …

    #
    # Controls who can get stuff from this server.
    #
trick1    <RequireAll>
        Include ../apache-conf/httpd-lan-access.conf
trick2        Include ../apache-conf/httpd-freedumbytes-realm.conf
trick1    </RequireAll>
</Directory>

 …

#
# "P:/dev/apps/httpserver/apache-2.4.16/cgi-bin" should be changed to whatever
# your ScriptAliased CGI directory exists, if you have that configured.
#
<Directory "P:/dev/apps/httpserver/apache-2.4.16/cgi-bin">
    AllowOverride None
    Options None

trick1    <RequireAll>
        Include ../apache-conf/httpd-lan-access.conf
trick2        Include ../apache-conf/httpd-freedumbytes-realm.conf
trick1    </RequireAll>
</Directory>

7.1.5. Home page

Make the freedumbytes.dev.net Home page content upgrade safe by changing its location 1 and 2 in P:\dev\apps\httpserver\apache-2.4.16\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.4.16/htdocs
              P:/dev/data/httpserver/hometrick1"
<Directory "P:/dev/apps/httpserver/apache-2.4.16/htdocs
            P:/dev/data/httpserver/hometrick2">
     …

    #
    # Controls who can get stuff from this server.
    #
    <RequireAll>
        Include ../apache-conf/httpd-lan-access.conf
        Include ../apache-conf/httpd-freedumbytes-realm.conf
    </RequireAll>
</Directory>

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

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

<body>
  <p>Redirecting to 
    <a href="http://freedumbytes.dev.net/mvn-sites/maven-setup/">
      http://freedumbytes.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.

7.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.4.16\conf\httpd.conf:

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

Also block Internet access 2 based on ips 3 with basic authentication 4 for the manual and take into account the custom installation 1 in P:\dev\apps\httpserver\apache-2.4.16\conf\extra\httpd-manual.conf:

AliasMatch ^/manual(?:/(?:da|de|en|es|fr|ja|ko|pt-br|ru|tr|zh-cn))?(/.*)?$ 
           "c:/Apache24/manualP:/dev/apps/httpserver/apache-2.4.16/manual$1"trick1

trick1<Directory "c:/Apache24P:/dev/apps/httpserver/apache-2.4.16/manual">
    Options Indexes
    AllowOverride None
trick2    Require all granted

trick2    <RequireAll>
trick3        Include ../apache-conf/httpd-lan-access.conf
trick4        Include ../apache-conf/httpd-freedumbytes-realm.conf
trick2    </RequireAll>

   …
</Directory>

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

7.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 freedumbytes.dev.net configuration add the following line 1 in P:\dev\apps\httpserver\apache-2.4.16\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 freedumbytes.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 freedumbytes.dev.net virtual host 2-5 on port 80 1:

LogFormat "%v %h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"" vcombined

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

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

Note

It is also possible to create subdomains with VirtualHost (see also Section 7.1.9.1.1.1, “Subdomain sample”).

trickIn C:\WINDOWS\system32\drivers\etc\hosts file add the following mapping (on all developer machines that want to access http://freedumbytes.dev.net and subdomains on the above configured host machine1-2):

# 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

192.168.0.xx freedumbytes.dev.nettrick1
192.168.0.xx sample.freedumbytes.dev.nettrick2

127.0.0.1    mail.freedumbytes.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, freedumbytes.dev.net, 192.168.0.0/16.

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

7.1.7.1. Firewall configuration

To allow requests from other machines in the local area network select Start MenuControl PanelSystem and SecurityWindows FirewallAdvanced settings and under Windows Firewall with Advanced Security on Local ComputerInbound Rules create a New Rule…:

  • Rule Type: Port and click Next.

  • Protocol and Ports: TCP for Specific local ports 80 and click Next.

  • Action: Allow the connection and click Next.

  • Profile: Private only and click Next.

  • Name: Apache HTTP Server freedumbytes.dev.net and click Finished.

Note

It is possible that there are already two TCP and UDP rules for Apache HTTP Server when the Firewall notification has popped up. Optionally disable those.

Further restrict the Apache HTTP Server freedumbytes.dev.net rule by right clicking and set PropertiesPrograms and Services to This Program P:\dev\apps\httpserver\apache-2.4.16\bin\httpd.exe.

7.1.8. Module mod_macro configuration

Mod_macro allows the definition and use of macros within apache runtime configuration files. It is included in Apache Lounge httpd-x.x.x.zip.

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

7.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, 2 and at the end of the VirtualHost settings add the following proxy configuration 3-8:

LoadModule proxy_module modules/mod_proxy.sotrick1
LoadModule proxy_http_module modules/mod_proxy_http.sotrick2

LogFormat "%v %h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"" vcombined

<VirtualHost *:80>
  ServerAdmin http.webmaster@company.org
  ServerName freedumbytes.dev.net
  ErrorLog "P:/dev/logs/httpserver/freedumbytes.dev.net-error.log"
  CustomLog "P:/dev/logs/httpserver/freedumbytes.dev.net-access.log" vcombined

  <IfModule proxy_module>trick3
  <IfModule proxy_http_module>trick4
    ProxyRequests Offtrick5
    ProxyPreserveHost Ontrick6

    <Proxy *>trick7
      <RequireAll>
        Include ../apache-conf/httpd-lan-access.conftrick8
        Include ../apache-conf/httpd-freedumbytes-realm.conftrick9
      </RequireAll>
    </Proxy>trick7
  </IfModule>trick4
  </IfModule>trick3
</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”).

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

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

LogFormat "%v %h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"" vcombined

<VirtualHost *:80>
7.1.9.1.1.1. Subdomain sample

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

<VirtualHost *:80>
  ServerAdmin http.webmaster@shadowland.demon.nl
  ServerName freedumbytes.dev.net
  …

  # Sample
  Redirect /sample http://sample.freedumbytes.dev.net
</VirtualHost>

# Sample subdomain
Include ../apache-conf/httpd-sample-subdomain.conftrick1

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

<IfModule proxy_module>
<IfModule proxy_http_module>
<IfModule proxy_ajp_module>
<VirtualHost *:80>
  ServerName sample.freedumbytes.dev.net
  ErrorLog "P:/dev/logs/httpserver/freedumbytes.dev.net-error.log"
  CustomLog "P:/dev/logs/httpserver/freedumbytes.dev.net-access.log" vcombined

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

  <Location /http-sample>
    <RequireAll>
      Include ../apache-conf/httpd-lan-access.conf
      Include ../apache-conf/httpd-freedumbytes-realm.conf
    </RequireAll>
  </Location>

  ProxyPass /ajp-sample        ajp://localhost:8069/ajp-sample
  ProxyPassReverse /ajp-sample ajp://localhost:8069/ajp-sample

  <Location /ajp-sample>
    <RequireAll>
      Include ../apache-conf/httpd-lan-access.conf
      Include ../apache-conf/httpd-freedumbytes-realm.conf
    </RequireAll>
  </Location>
</VirtualHost>
</IfModule>
</IfModule>
</IfModule>

Prepackaged 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://sample.freedumbytes.dev.net/http-sample, http://freedumbytes.dev.net/sample/http-sample and http://sample.freedumbytes.dev.net/ajp-sample.

Important

For this to work all URL references need to be relative (see also Section 7.1.9.2, “Html rewrite configuration”).

7.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 or Apache Lounge modules archive: mod_jk-1.2.41-win64-VC14.zip [version 1.2.41].

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/freedumbytes.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
7.1.9.1.2.1. Sample

Extend the P:\dev\apps\httpserver\apache-conf\httpd-sample-subdomain.conf from Section 7.1.9.1.1.1, “Subdomain sample” to mount /jk-sample 1:

<IfModule proxy_module>
<IfModule proxy_http_module>
<IfModule proxy_ajp_module>
<VirtualHost *:80>
  ServerName sample.freedumbytes.dev.net
  …

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

  <Location /jk-sample>
    <RequireAll>
      Include ../apache-conf/httpd-lan-access.conf
      Include ../apache-conf/httpd-freedumbytes-realm.conf
    </RequireAll>
  </Location>
</VirtualHost>
</IfModule>
</IfModule>
</IfModule>

A prepackaged 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://sample.freedumbytes.dev.net/jk-sample.

Important

For this to work all URL references need to be relative (see also Section 7.1.9.2, “Html rewrite configuration”).

7.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. It is included in Apache Lounge httpd-x.x.x.zip.

To make the upcoming changes upgrade safe copy and rename the initial P:\dev\apps\httpserver\apache-2.4.16\conf\extra\proxy-html.conf to P:\dev\apps\httpserver\apache-conf\httpd-proxy-html.conf. Thus when upgrading just use WinMerge to look for changes between the proxy-html.conf files in both unzipped httpd-x.x.x.zip versions with fc p:\dev\apps\httpserver\apache-2.4.10\conf\extra\proxy-html.conf p:\dev\apps\httpserver\apache-2.4.16\conf\extra\proxy-html.conf. Apply possible changes in P:\dev\apps\httpserver\apache-conf\httpd-proxy-html.conf.

In the initial copy P:\dev\apps\httpserver\apache-conf\httpd-proxy-html.conf load the modules 1-2:

# Configuration example.
   …
# For Windows (I don't know if there's a standard path for the libraries)
# LoadFile C:/path/zlib.dll 
# or LoadFile "P:/dev/apps/httpserver/apache-2.4.16/bin/zlib1.dll"
# LoadFile C:/path/iconv.dll
# or LoadFile "P:/dev/apps/httpserver/apache-2.4.16/bin/libapriconv-1.dll"
# LoadFile C:/path/libxml2.dll
# or LoadFile "P:/dev/apps/httpserver/apache-2.4.16/bin/libxml2.dll"
trick1LoadModule proxy_html_module modules/mod_proxy_html.so
trick2LoadModule xml2enc_module 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

Note

The other files zlib1.dll, libiconv2.dll and libxml2.dll are already available in P:\dev\apps\httpserver\apache-2.4.16\bin.

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

LoadModule proxy_html_module modules/mod_proxy_html.so
LoadModule xml2enc_module 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

Finally remove the now superfluous include 1 in P:\dev\apps\httpserver\apache-2.4.16\conf\httpd.conf:

# Configure mod_proxy_html to understand HTML4/XHTML1
#<IfModule proxy_html_module>trick1
#Include conf/extra/proxy-html.conftrick1
#</IfModule>trick1
7.1.9.2.1. Sample

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

Important

Notice the difference between http://sample.freedumbytes.dev.net/http-sample and http://freedumbytes.dev.net/tomcat/http-sample/ for the absolute URL reference due to ProxyHTMLURLMap http://localhost:8068 /tomcat.

7.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 archive mod_wsgi-windows-4.4.12.tar.gz. After extracting this archive move mod_wsgi-windows-4.4.12\Apache24-win64-VC10\modules\mod_wsgi-py34-VC10.so to P:\dev\apps\httpserver\apache-conf\modules\mod_wsgi.so [version 4.4.12].

Or download the alternative archive mod_wsgi-4.4.13+ap24vc10-cp34-none-win_amd64.whl (just rename to .zip). After extracting this archive move mod_wsgi-4.4.13+ap24vc10-cp34-none-win_amd64\mod_wsgi-4.4.13+ap24vc10.data\data\mod_wsgi.so to P:\dev\apps\httpserver\apache-conf\modules\mod_wsgi.so [version 4.4.13].

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:

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

<IfModule mod_wsgi.c>
  <Location /python-status>
#    Include ../apache-conf/httpd-lan-access.conf
    Include ../apache-conf/httpd-localhost-access.conf
  </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 =  b'Hello World\r\r\r' + pprint.pformat(environ).encode('utf8')

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

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

Important

Alas haven't found a x64 Apache HTTP Server 2.4.x Perl 5.18 binary yet. Thus mod_perl is no longer available after current upgrades.

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

LoadModule perl_module P:/dev/apps/httpserver/apache-conf/modules/mod_perl.so

<IfModule mod_perl.c>
  <Location /perl-status>
    SetHandler perl-script
    PerlHandler Apache2::Status
    PerlSetVar StatusOptionsAll On

    Include ../apache-conf/httpd-localhost-access.conf
  </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 /perl-sample>
    SetHandler modperl
    PerlResponseHandler sample::perl::test

    Include ../apache-conf/httpd-localhost-access.conf
  </Location>
</IfModule>

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

7.1.12. Module mod_php5 configuration

php5apache2_4.dll is needed to allow Apache to use PHP.

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

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

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

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

LoadModule php5_module "P:/dev/apps/prg/php-5.6.13/php5apache2_4.dll"

<IfModule mod_php5.c>
  AddHandler application/x-httpd-php .php .php5
  PHPIniDir "P:/dev/apps/prg/php-5.6.13/"

  <Location /status.php>
    Include ../apache-conf/httpd-localhost-access.conf
  </Location>

  <Location /status.php5>
    Include ../apache-conf/httpd-localhost-access.conf
  </Location>
</IfModule>

Create the following file P:\dev\data\httpserver\home\status.php and/or P:\dev\data\httpserver\home\status.php5:

<?php echo "Hello World"; ?>

<?php phpinfo(); ?>

Edit 1t-2 in the file P:\dev\apps\prg\php-5.6.13\php.ini:

; The root of the PHP pages, used only if nonempty.
; if PHP was not compiled with FORCE_REDIRECT, you SHOULD set doc_root
; if you are running php as a CGI under any web server (other than IIS)
; see documentation for security issues.  The alternate is to use the
; cgi.force_redirect configuration below
; http://php.net/doc-root
trick1doc_root = P:\dev\data\httpserver\home

 …

; Directory in which the loadable extensions (modules) reside.
; http://php.net/extension-dir
; extension_dir = "./"
; On windows:
; extension_dir = "ext"
trick2extension_dir = P:\dev\apps\prg\php-5.6.13\ext

After the Apache HTTP Server is restarted test the mod_php5 by taking a look at the PHP Status.

7.1.13. 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.4.16\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

    <RequireAll>
      Include ../apache-conf/httpd-lan-access.conf
      Include ../apache-conf/httpd-freedumbytes-realm.conf
    </RequireAll>
  </Directory>
</IfModule>
</IfModule>
</IfModule>

Don't forget to create the specified directories: P:\dev\data\httpserver\webdav and P:\dev\data\httpserver\mvn\sites. After the Apache HTTP Server is restarted take a look at http://freedumbytes.dev.net/mvn-sites/.

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

To make the upcoming changes upgrade safe initially copy the P:\dev\apps\httpserver\apache-2.4.16\conf\extra\httpd-info.conf to P:\dev\apps\httpserver\apache-conf\httpd-info.conf. Thus when upgrading this functionality doesn't have to be reconfigured again.

Include 1 the real-time info configuration at the top in P:\dev\apps\httpserver\apache-conf\httpd.conf:

# Real-time info on requests and configuration
trick1Include ../apache-conf/httpd-info.conf

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

In the copy P:\dev\apps\httpserver\apache-conf\httpd-info.conf load the modules 1-2 and restrict access 3 to localhost:

trick1LoadModule info_module modules/mod_info.so
trick2LoadModule status_module modules/mod_status.so

 …

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

<Location /server-status>
  SetHandler server-status
  Include ../apache-conf/httpd-localhost-access.conftrick3
</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 Ontrick4

#
# Allow remote server configuration reports, with the URL of
#  http://servername/server-info (requires that mod_info.c be loaded).
# Change the ".example.com" to match your domain to enable.
#
<Location /server-info>
  SetHandler server-info
  Include ../apache-conf/httpd-localhost-access.conftrick3
</Location>

Note

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

Chapter 8. Web Server

8.1. Tomcat

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

8.1.1. Resources

8.1.2. Tomcat installation guide

Download the archive: apache-tomcat-8.0.26-windows-x64.zip [version 8.0.26].

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

8.1.2.1. HTTP Binding

Configure Tomcat settings 1-7 in the file P:\dev\apps\webserver\apache-tomcat-8.0.26\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/>

8.1.2.2. Tomcat access

Configure Tomcat access in the file P:\dev\apps\webserver\apache-tomcat-8.0.26\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:

8.1.3. Windows service

To restart automatically on Microsoft Windows create a service using an elevated command prompt as follows:

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

set JAVA_HOME=P:\dev\apps\prg\java-x64\jdk1.8.0_121
set CATALINA_HOME=P:\dev\apps\webserver\apache-tomcat-8.0.26
bin\service.bat install tomcat

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

bin\tomcat8.exe //US//tomcat --JvmMx=512 --JvmMs=128

Start it with net start tomcat.

Note

In case of an upgrade sc delete tomcat first (see also Section 1.1.5, “Task Manager replacement” in case of The specified service has been marked for deletion.).

Important

In case of a new jdk installation just run P:\dev\apps\webserver\apache-tomcat-8.0.26\bin\tomcat8.exe //US//tomcat --Jvm auto (when JAVA_HOME is still pointing to the 64-bit version; see also Section 8.1.3.2, “Tomcat Manager”).

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

8.1.3.1. Log On 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. Also Change the picture with Browse for more pictures… P:\dev\apps\webserver\apache-tomcat-8.0.26\webapps\ROOT\tomcat.png and click Open.

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

8.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 freedumbytes.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 freedumbytes.dev.net.

Important

The usage of Section 14.1.4.4, “Git authentication” is a better alternative.

Restart tomcat service to pick up the HOME setting.

8.1.3.2. Tomcat Manager

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

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

When the Tomcat Manager is running, you can see the freedumbytes.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 was already running when the Log On account was changed (as described in the prior Section 8.1.3.1, “Log On Windows user”) right click on its icon and select Exit and then restart it. Because this change wont show up otherwise.

Tip

As an alternative to change the additional settings of the Tomcat service run: P:\dev\apps\webserver\apache-tomcat-8.0.26\bin\tomcat8w.exe //MS//tomcat such as JavaJava Virtual Machine P:\dev\apps\prg\java-x64\jdk1.8.0_121\jre\bin\server\jvm.dll.

8.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 after shutting down tomcat with net stop tomcat:

  1. Tomcat replacements:

    • Download: tomcat-juli-adapters.jar and tomcat-juli.jar [version 8.0.26].

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

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

  2. Log4J integration:

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

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

  3. SLF4J integration:

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

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

    • And bind SLF4J to Log4J by installing the slf4j-log4j12-1.7.12.jar in the P:\dev\apps\webserver\apache-tomcat-8.0.26\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-8.0.26\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-8.0.26
      
      bin\tomcat8.exe //US//tomcat ^
        ++JvmOptions=-Dlog4j.configuration=^
          file:///P:/dev/logs/webserver/tomcat/log4j.xml
      
      bin\tomcat8.exe //US//tomcat ^
        --LogPath=P:/dev/logs/webserver/tomcat
      

      Open the Tomcat Manager in the system tray by right clicking on this icon and selecting Configure. In the Java tab remove the now obsolete Java Options parameter -Djava.util.logging.config.file=P:\dev\apps\webserver\apache-tomcat-8.0.26\conf\logging.properties.

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

    <RequireAll>
      Include ../apache-conf/httpd-lan-access.conftrick1
    </RequireAll>
  </Location>
</IfModule>
</IfModule>
</IfModule>
</IfModule>

Important

Notice that only local access 1 is activated and not the freedumbytes.dev.net realm because this clashes with the basic authentication of Tomcat itself resulting in the following error AH01618: user admin not found: /tomcat/manager/status, referer: http://freedumbytes.dev.net/tomcat/ and hanging HTTP requests.

8.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-8.0.26\conf\server.xml:

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

This can be useful for passing on authenticated users to for example applications such as Jenkins.

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

Chapter 9. Application Server

9.1. Payara

Payara Server is a drop in replacement for GlassFish Server Open Source Edition, with the peace of mind of quarterly releases containing enhancements, bug fixes and patches (see also the Data Sheet). Payara Server is derived from GlassFish Server Open Source Edition and 100% open source at GitHub.

There is also Payara Micro, which enables you to run war files from the command line without any application server installation. It is small, < 70MB in size and incredibly simple to use. With its automatic and elastic clustering, Payara Micro is designed for running Java EE applications in a modern containerized/virtualized infrastructure, using automated provisioning tools like Chef, Ansible or Puppet (see also the Data Sheet).

9.1.1. Resources

9.1.2. Payara installation guide

Download the archive: payara-4.1.1.163.zip [version 4.1.1.163].

Extract the .zip file to P:\dev\apps\appserver and rename P:\dev\apps\appserver\payara41 to P:\dev\apps\appserver\payara-4.1.1.163.

Important

New since release 152 is the extra payaradomain template.

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\payara-4.1.1.163\glassfish\domains\payaradomain\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="80808071trick4" 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>
   <config name="default-config" dynamic-reconfiguration-enabled="true" >
       …
      <iiop-service>
         …
        <iiop-listener port="${IIOP_LISTENER_PORT}" … 
              address="0.0.0.0127.0.0.1trick1" />
        <iiop-listener port="${IIOP_SSL_LISTENER_PORT}" … 
              address="0.0.0.0127.0.0.1trick1" …>
         …
        </iiop-listener>
        <iiop-listener port="${IIOP_SSL_MUTUALAUTH_PORT}" … 
              address="0.0.0.0127.0.0.1trick1" …>
         …
        </iiop-listener>
      </iiop-service>
      <admin-service system-jmx-connector-name="system" type="server">
        <jmx-connector address="0.0.0.0192.168.0.xxtrick3" … 
             port="${JMX_SYSTEM_CONNECTOR_PORT}" …/>
         …
      </admin-service>
       …
      <network-config>
          …
        <network-listeners>
          <network-listener address="127.0.0.1"trick1 
                   port="${HTTP_LISTENER_PORT}" … />
          <network-listener address="127.0.0.1"trick1 
                   port="${HTTP_SSL_LISTENER_PORT}" … />
          <network-listener address="192.168.0.xx"trick3 
                   port="${ASADMIN_LISTENER_PORT}" … />
        </network-listeners>
       …
      </network-config>
     …
    </config> 
  </configs>
  <property name="administrative.domain.name" value="domain1"/>
</domain>

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

For administration tasks, the Payara 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.

Start the server by entering the command asadmin start-domain payaradomain.

Show domains running on the server by entering the command asadmin list-domains.

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

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

9.1.3. Changing JDK version

Updating Payara 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\payara-4.1.1.163\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 Payara should use.
REM As a result, in order to run a user-specified version of Java, the asadmin 
REM and appclient scripts do indeed invoke this file as a script - but ONLY to
REM define AS_JAVA.  Any calling script should not rely on the other settings 
REM because the relative paths will be resolved against the current directory 
REM when the calling script is run, not the installation directory of Payara, 
REM and such resolution will not work correctly unless the script happens to be 
REM run from the Payara installation directory.
 …
set AS_JAVA=P:\dev\apps\prg\java-x64\jdk1.8.0_121

9.1.4. Autodeploy

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

Just copy the application, which is packaged as Java ARchive (JAR), Web ARchive (WAR), or Enterprise ARchive (EAR) file, into p:\dev\apps\appserver\payara-4.1.1.163\glassfish\domains\payaradomain\autodeploy\ or run for example: asadmin -H freedumbytes.dev.net deploy --force p:\dev\tools\appserver\hello.war (use --force for redeployment).

9.1.5. Admin console

Access http://freedumbytes.dev.net:4848. Enter the admin user name and password. Change/Set the admin password at DomainAdministrator 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.

9.1.6. Apache configuration

Instruct Apache to proxy all URLs whose path portions begin with /payara/ 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>

    # Payara
    Include ../apache-conf/httpd-payara.conftrick1
  </IfModule>
  </IfModule>
</VirtualHost>

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

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

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

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

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

9.1.7. Windows service

To restart automatically on Microsoft Windows create a service using an elevated command prompt as follows:

cd /d P:\dev\apps\appserver\payara-4.1.1.163

set JAVA_HOME=P:\dev\apps\prg\java-x64\jdk1.8.0_121
set PAYARA_HOME=P:\dev\apps\appserver\payara-4.1.1.163
asadmin create-service payaradomain

dir payaradomainService.xml /s

Note

In case of an upgrade sc delete payara first (see also Section 1.1.5, “Task Manager replacement” in case of The specified service has been marked for deletion.).

Edit the following entries 1-3 in the newly generated service configuration file p:\dev\apps\appserver\payara-4.1.1.163\glassfish\domains\payaradomain\bin\payaradomainService.xml:

<service>
  <id>payaradomainpayaratrick1</id>
  <name>payaradomain Payara Serverfreedumbytes.dev.net Payaratrick2</name>
  <description>Payara ServerPayara Application Servertrick3</description>
  <executable>
    P:/dev/apps/appserver/payara-4.1.1.163/glassfish/lib/nadmin.bat
  </executable>
  <logpath>
    P:\\dev\\apps\\appserver\\payara-4.1.1.163\\glassfish\\domains/payaradomain/bin
  </logpath>
  <logmode>reset</logmode>
  <depend>tcpip</depend>
  <startargument>start-domain</startargument>
  <startargument>--watchdog</startargument>
  <startargument>--domaindir</startargument>
  <startargument>
    P:\\dev\\apps\\appserver\\payara-4.1.1.163\\glassfish\\domains
  </startargument>
  <startargument>payaradomain</startargument>
  <stopargument>stop-domain</stopargument>
  <stopargument>--domaindir</stopargument>
  <stopargument>
    P:\\dev\\apps\\appserver\\payara-4.1.1.163\\glassfish\\domains
  </stopargument>
  <stopargument>payaradomain</stopargument>
</service>

Activate those changes with:

cd glassfish\domains\payaradomain\bin\

sc delete payaradomain
payaradomainService.exe install

Important

The payaradomainService.exe install must be run in its directory glassfish\domains\payaradomain\bin\ otherwise the following error System error 2 has occurred. The system cannot find the file specified. will occur during net start payara.

Start it with net start payara.

Verify the installation at http://freedumbytes.dev.net/payara.

9.1.7.1. Log On Windows user

For the same reason as Section 8.1.3.1, “Log On Windows user” launch the Service Management Console with services.msc. Right click on freedumbytes.dev.net Payara and select PropertiesLog On to use This account .\Tomcat. After password conformation click Apply and restart the service.

Chapter 10. Database

10.1. MySQL

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

10.1.1. Resources

10.1.2. MySQL installation guide

Download the archive: mysql-5.6.26-winx64.zip [version 5.6.26].

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

trickPress +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.6.26-winx64.

Verify the installation with mysql --version.

10.1.2.1. Custom data directory

Initialize a custom MySQL data directory with a copy of the installation data folder P:\dev\apps\db\mysql-5.6.26-winx64\data from the command line with xcopy /E /I P:\dev\apps\db\mysql-5.6.26-winx64\data K:\dev\data\db\mysql\data.

Create a MySQL Server configuration file K:\dev\data\db\mysql\conf\mysql-master.ini:

[mysqld]
basedir="P:/dev/apps/db/mysql-5.6.26-winx64"
datadir="K:/dev/data/db/mysql/data"
tmpdir="K:/dev/data/db/mysql/tmp"
log-error="K:/dev/data/db/mysql/mysql-master-error.log"
port=3306
server_id=3306
default-storage-engine=INNODB
explicit_defaults_for_timestamp=true
sql-mode="STRICT_TRANS_TABLES,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION"

Important

To avoid the error InnoDB: Error: unable to create temporary file; errno: 2 create the tmpdir with mkdir K:\dev\data\db\mysql\tmp.

From the command line start MySQL Server with mysqld --defaults-file=K:\dev\data\db\mysql\conf\mysql-master.ini.

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

To shutdown the SQL Server use mysqladmin -u root --port=3306 shutdown.

10.1.2.2. MySQL character set configuration

Change the default character set and collation in K:\dev\data\db\mysql\conf\mysql-master.ini:

[client]
default-character-set=utf8mb4

[mysql]
default-character-set=utf8mb4

[mysqld]
 …

character-set-client-handshake=false
character-set-server=utf8mb4
collation-server=utf8mb4_unicode_ci

Verify those settings before and after restarting service mysql-1 with:

mysql -u root
mysql> show variables where variable_name
    ->  like 'character\_set\_%' or variable_name LIKE 'collation%';
mysql> quit

10.1.2.3. MySQL root password

If you have never set a root password for MySQL server, the server does not require a password at all for connecting as root. To setup root password for first time, use mysqladmin command at shell prompt as follows and enter and confirm the new password:

mysqladmin -u root password

However, if you want to change a root password, then you need to use the following command and enter the old password followed by the new password:

mysqladmin -u root -p  password

10.1.3. Windows service

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="freedumbytes.dev.net MySQL %1"
set SERVICE_EXE=%MYSQL_HOME%\bin\mysqld.exe
set SERVICE_START_CMD=--defaults-file=\"K:\dev\data\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 service for the master from an elevated command prompt with: mysql-create-service master. Start the server with sc start mysqlmaster or net start mysqlmaster.

10.1.3.1. Log On Windows user

For the same reason as Section 8.1.3.1, “Log On Windows user” launch the Service Management Console with services.msc. Right click on freedumbytes.dev.net MySQL master and select PropertiesLog On to use This account .\Tomcat. After password conformation click Apply and restart the service.

10.1.4. 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 S:\dev\backup\db\mysqldump mkdir S:\dev\backup\db\mysqldump
    cd /d S:\dev\backup\db\mysqldump
    mysqldump --single-transaction --routines --triggers -q --all-databases ^
              -u root -p > S:\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 S:\dev\backup\db\mysqldump mkdir S:\dev\backup\db\mysqldump
    cd /d S:\dev\backup\db\mysqldump
    mysqldump --single-transaction --routines --triggers -q %1 ^
              -u root -p > S:\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. And import will look like mysql -u root -p mysql < S:\dev\backup\db\mysqldump\mysql.20091205.sql.

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

10.1.5. Upgrading

Backup the mysql database separately, for example:

mysql-backup-db mysql 20150917
mysql-backup-db fisheye 20150917
mysql-backup-db jira 20150917
mysql-backup-db sonarqube 20150917
mysql-backup-db test 20150917

Or stop the master service (after stopping services that might rely on a database such as payara, tomcat, fisheye, jira and sonarqube):

net stop mysqlmaster

And create a binary backup of the MySQL configuration and the data directory:

xcopy /E /I K:\dev\data\db\mysql S:\dev\backup\db\mysql-20150917

After extracting the latest zip as described in installation guide and updating MYSQL_HOME also update the basedir 1 in K:\dev\data\db\mysql\conf\mysql-master.ini:

[mysqld]
basedir="P:/dev/apps/db/mysql-5.6.26-winx64"trick1

Note

In case of an upgrade sc delete mysqlmaster first (see also Section 1.1.5, “Task Manager replacement” in case of The specified service has been marked for deletion.).

Redefine the Windows service for the master: mysql-create-service master.

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.

Finally upgrade the master tables with mysql_upgrade -P 3306 -u root -p. After successfully running this command, type K:\dev\data\db\mysql\data\mysql_upgrade_info should display: 5.6.26.

10.1.6. 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.5.3.46192].

Extract this .zip file to C:\tmp and run the C:\tmp\MyManagerLite.msi 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.

10.1.7. 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: navicat111_mysql_en_x64.exe [version 11.1.13].

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.

10.2. Oracle

Oracle Database.

10.2.1. Resources

  • Oracle Database Software Downloads.

  • Get Oracle JDBC drivers from the Oracle Maven Repository.

  • Oracle SQL Developer is a free integrated development environment that simplifies the development and management of Oracle Database in both traditional and Cloud deployments. SQL Developer offers complete end-to-end development of your PL/SQL applications, a worksheet for running queries and scripts, a DBA console for managing the database, a reports interface, a complete data modeling solution, and a migration platform for moving your 3rd party databases to Oracle.

Chapter 11. Version Control System

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

11.1.1. Resources

11.1.2. Git installation guide

Download the binary: Git-2.10.2-64-bit.exe [version 2.10.2].

Run this .exe file to install Git in P:\dev\apps\vcs\git with the default settings.

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

11.1.2.1. Git bash home directory

Right-click on the shortcut for Git Bash and change PropertiesStart in from %HOMEDRIVE%%HOMEPATH% to C:\dev\projects and remove -cd option from the Target.

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 it isn't. For example git clo versus git cl (with suggestions: clean clone).

11.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 jene.jasper@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 --global push.default simple

git config --list

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

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

11.1.2.5. Ignores template

Create the following ignores template P:\dev\data\repo\.gitignore based on Java.gitignore and Maven.gitignore of .gitignore templates:

#general
*.bak
*~
*.log

#compiled
*.com
*.class
*.dll
*.exe
*.o
*.so

#archive
*.jar
*.ear
*.war

#eclipse
.classpath
.project
.settings/

#maven
target/
pom.xml.tag
pom.xml.releaseBackup
pom.xml.versionsBackup
pom.xml.next
release.properties

#cvs
CVS/
.cvsignore

#subversion
.svn/

11.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' …
[branch]
  autosetuprebase = always
[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 C:\dev\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 C:\dev\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 C:\dev\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 C:\dev\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

11.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>
    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/mingw64/libexec/git-core/git-http-backend.exe/$1

    <Location $git_uri>
        Include ../apache-conf/httpd-freedumbytes-realm.conf
    </Location>
  </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.

11.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>
    …
    <Location $git_uri>
      Include ../apache-conf/httpd-freedumbytes-realm.conf
    </Location>

    SetEnv GITWEB_CONFIG P:/dev/data/httpserver/home/git/$gitweb_conftrick1

    Alias $git_uri/static P:/dev/apps/vcs/git/mingw64/share/gitweb/statictrick1

    ScriptAlias $git_uri \
                P:/dev/apps/vcs/git/mingw64/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

11.1.4.2. GitWeb Perl implementation

Because GitWeb isn't working with ActivePerl configure it to use the supplied Perl implementation of mysysGit in P:\dev\apps\vcs\git\mingw64\share\gitweb\gitweb.cgi:

#!/usr/bin/perlP:/dev/apps/vcs/git/usr/bin/perl.exetrick1

But this one is missing the CGI.pm module. Just copy it from ActivePerl:

copy P:\dev\apps\prg\perl-5.22.0.2200\lib\CGI.pm ^
     P:\dev\apps\vcs\git\mingw64\share\gitweb

xcopy /E /I P:\dev\apps\prg\perl-5.22.0.2200\lib\CGI ^
            P:\dev\apps\vcs\git\mingw64\share\gitweb\CGI

When the Apache HTTP Server is restarted you should be able to browse the Git Repository at http://freedumbytes.dev.net/git-repo.

11.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 with the following changes in P:\dev\apps\httpserver\apache-conf\httpd-vhosts.conf:

<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

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

or upgrade with:

cd /d P:\dev\data\httpserver\home\git\gitweb-theme
git pull

Configure the theme in P:/dev/data/httpserver/home/git/gitweb.conf:

 …
$stylesheet = "git-repo/staticgitweb-theme/gitweb.css";
$logo = "git-repo/staticgitweb-theme/git-logo.png";
$favicon = "git-repo/staticgitweb-theme/git-favicon.png";
$javascript = "git-repo/staticgitweb-theme/gitweb.js";
 …

Point Apache HTTP Server to the correct location in P:\dev\apps\httpserver\apache-conf\httpd-git-macro.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://freedumbytes.dev.net/git-repo.

11.1.5. Defining a project

Create a shell script P:\dev\apps\windows\batch\git-create-repo.sh:

#!/bin/bash

if [ $# -lt 3  ]
then
  echo "Usage: git-create-repo <git-repo-location> <project-name> \"<project-description>\" [-jenkinsHook]."
  exit 9
else
  git_repo="$1"
  project_name="$2"
  project_description="$3"
  jenkins_hook="$4"

  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
    if [[ "$jenkins_hook" == "-jenkinsHook" ]]
    then
      echo "Setup Jenkins git hook"
      echo "#!/bin/sh" > hooks/post-receive
      echo "" >> hooks/post-receive
      echo "curl http://freedumbytes.dev.net/jenkins/git/notifyCommit?url=http://freedumbytes.dev.net/git-repo/$project_name" >> hooks/post-receive
    else
      echo "DONT setup Jenkins git hook"
    fi
    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 "freedumbytes.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. If you're using Git to collaborate with others on GitHub, GitLab and Bitbucket, ensure that Git is properly configured to handle line endings. Speaking about those repository management services take a look at Appendix B, Hosting a group Website in the Cloud and Section B.5, “Multiple remote git locations”.

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

11.1.5.1. Anonymous Jenkins Notify Hook

To enable anonymous access from the local area network 2 to the Jenkins hook 1 edit P:\dev\apps\httpserver\apache-conf\httpd-jenkins.conf:

<IfModule proxy_module>
<IfModule proxy_ajp_module>
  AllowEncodedSlashes NoDecode
  ProxyPass /jenkins        ajp://localhost:8069/jenkins nocanon
  ProxyPassReverse /jenkins ajp://localhost:8069/jenkins

  <Location /jenkins>
    Include ../apache-conf/httpd-freedumbytes-realm.conf
  </Location>

  <Location /jenkins/git/notifyCommit>trick1
    <RequireAll>
      Include ../apache-conf/httpd-lan-access.conftrick2
    </RequireAll>
  </Location>
</IfModule>
</IfModule>

11.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 C:\dev\projects
if exist \projects\%2 ren "%2" "%2.old"
git clone http://%1@freedumbytes.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 C:\dev\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).

11.2. Subversion (SVN) client only

Subversion is a version control system that is a compelling replacement for CVS in the open source community.

11.2.1. Resources

  • Download prepackaged binaries.

  • Upgrade checklist:

    • Related products: -.

    • References: -.

    • Integration configuration changes: -.

  • The Subversion Book: Version Control with Subversion.

  • Subversion Quick Start, Complete Reference and CVS to SVN Crossover Guide.

  • SVNKit is a pure Java Subversion library. You would like to use SVNKit when you need to access or modify Subversion repository from your Java application, be it a standalone program, plugin or web application.

11.2.2. Subversion installation guide

Download the archive (alternative location): svn-win32-1.8.14-ap24.zip for Apache 2.4.x [version 1.8.14].

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

trickPress +Break keys to open the Windows System Properties. Select Advanced system settingsEnvironment Variables and Edit the Path to append %SVN_HOME%\bin;. Also add a New system variable SVN_HOME pointing to P:\dev\apps\vcs\svn-win32-1.8.14. Optionally add a New system variable SVN_EDITOR pointing to for example P:\dev\apps\editor\ultraedit\Uedit32.exe.

Verify the installation with svn --version.

11.2.3. Global ignores

Edit the %APPDATA%\subversion\config file to ignore Eclipse, Maven and backup files as follows:

### Section for configuring miscelleneous Subversion options.
[miscellany]
global-ignores = .classpath .project .settings target *.bak *~ *.log

11.2.4. Delete directories

To immediately delete a directory with its subdirectories use svn delete -m "Delete resources from project X." http://freedumbytes.dev.net/svn-repo/project-x/trunk/src/main/resources/.

This is useful when svn delete src\main\resources followed by svn commit -m "Delete resources from project X." results in svn: Aborting commit: 'C:\dev\projects\project-x\src\main\resources' remains in conflict.

11.2.5. Credentials

Sometimes users will want to remove specific credentials from the disk cache. To do this, you need to navigate into the %APPDATA%\Subversion\auth\svn.simple area and manually delete the appropriate cache file. Credentials are cached in individual files; if you look inside each file, you will see keys and values. The svn:realmstring key describes the particular server realm that the file is associated with, for example:

K 8
passtype
 …
K 15
svn:realmstring
V 61
<http://viewvc.tigris.org:80> CollabNet Subversion Repository
K 8
username
 …
END

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

11.3.1. Resources

11.3.2. FishEye installation guide

Download the archive: fisheye-3.9.1.zip [version 3.9.1].

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

trickPress +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-3.9.1.

Verify the installation with: .

cd /d %FISHEYE_HOME%
set JAVA_HOME=P:\dev\apps\prg\java-x64\jdk1.8.0_121
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 (or rename to start.bat.disable for example) because they redirect to fisheyectl.bat anyway.

Terminate the server with Ctrl+C.

trickFor the ease of future upgrades press +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-3.9.1\config.xml P:\dev\data\vcs\fisheye

  • mkdir %FISHEYE_INST%\lib

  • move P:\dev\apps\vcs\fecru-3.9.1\var P:\dev\data\vcs\fisheye

11.3.3. FishEye configuration

Restart FishEye again with fisheyectl start. Verify that the server is running in your browser at http://freedumbytes.dev.net:8060.

Note

In case of java.lang.OutOfMemoryError: PermGen space just set FISHEYE_OPTS=-Xmx512m -Xms128m before running fisheyectl start (see also Section 11.3.5, “Windows service”).

When you access FishEye for the first time you will be asked for:

  1. To Obtain evaluation license and Enter existing license.

  2. Please include Crucible as part of this evaluation.

  3. Skip for now Connect to JIRA.

  4. Create password and Confirm password.

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 http://freedumbytes.dev.net:8060/admin/ and configure FishEye.

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

  • Site URL: http://freedumbytes.dev.net/fisheye/.

  • Timezone : Europe/Amsterdam and click Update.

Select Global SettingsServerMail ServerEdit config:

  • Send mail from: Server Address (below).

  • From Address: fisheye.noreply@company.org.

  • SMTP Host name: mail.freedumbytes.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.

11.3.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>
  ProxyPass /fisheye        ajp://localhost:8061/fisheye
  ProxyPassReverse /fisheye ajp://localhost:8061/fisheye

#  ProxyPass /fisheye        http://localhost:8060/fisheye
#  ProxyPassReverse /fisheye http://localhost:8060/fisheye

#  <IfModule mod_jk.c>
#    JkMount /fisheye   fisheye
#    JkMount /fisheye/* fisheye
#  </IfModule>

  Alias /fisheye/static       "P:\dev\apps\vcs\fecru-3.9.1\content\static"

  ProxyPass /fisheye/static/  !

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

When the Apache HTTP Server is restarted you should be able to browse FishEye at http://freedumbytes.dev.net/fisheye.

11.3.4.1. Privacy Policy

Next configure if Analytics collects data about the usage of FishEye and sends it to Atlassian (see the privacy policy for details).

11.3.4.2. Security

Next configure at the FishEye Admin GUI http://freedumbytes.dev.net/fisheye/admin/ 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 User List Visibility and 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 freedumbytes.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.

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://freedumbytes.dev.net/fisheye/">
  <http bind="127.0.0.1:8060"/>trick1
  <ajp13 bind="127.0.0.1:8061"/>
</web-server>

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

Note

In case of an upgrade just copy the one extracted in the prior FishEye version:

copy P:\dev\apps\vcs\fecru-3.7.0\Fisheye-Control.* ^
     P:\dev\apps\vcs\fecru-3.9.1
xcopy /E /I P:\dev\apps\vcs\fecru-3.7.0\wrapper ^
      P:\dev\apps\vcs\fecru-3.9.1\wrapper

Optionally comment out the jmx entries 2 and edit the following entries 1-12 in the service wrapper configuration file P:\dev\apps\vcs\fecru-3.9.1\wrapper\conf\wrapper.conf:

 …

# Java Application
wrapper.java.command=P:\dev\apps\prg\java-x64\jdk1.8.0_121\bin\javatrick1

 …

# Java Additional Parameters
wrapper.java.additional.1=-server
wrapper.java.additional.2=-showversion
wrapper.java.additional.3=-Djava.awt.headless=true

# JDK 1.5 Additional Parameters for jmx
#trick2wrapper.java.additional.4=-Dcom.sun.management.jmxremote
#trick2wrapper.java.additional.5=-Dcom.sun.management.jmxremote.port=4242
#trick2wrapper.java.additional.6=-Dcom.sun.management.jmxremote.authenticate=false
#trick2wrapper.java.additional.7=-Dcom.sun.management.jmxremote.ssl=false
#trick2wrapper.java.additional.8=-Dcom.sun.management.jmxremote.password.file=./wrapper/jmxremote.password
#trick2wrapper.java.additional.9=-Dwrapper.mbean.name="wrapper:type=Java Service Wrapper Control"

wrapper.java.additional.104=-Dfile.encoding=UTF-8trick3
wrapper.java.additional.5=-Dfisheye.inst=%FISHEYE_INST%trick4
#wrapper.java.additional.6=-Xrstrick5 see also Section 3.1.3.1, “Standard Edition Tools Reference”

# Initial Java Heap Size (in MB)
wrapper.java.initmemory=256trick6

# Maximum Java Heap Size (in MB)
wrapper.java.maxmemory=1024trick7

 …

# Log file to use for wrapper output logging.
wrapper.logfile==var/log/wrapper.log%FISHEYE_INST%/var/log/wrapper.logtrick8

 …

#********************************************************************
# Wrapper Windows Properties
#********************************************************************
# Title to use when running as a console
wrapper.console.title=Fisheyefreedumbytes.dev.net FishEyetrick9

#********************************************************************
# 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=Fisheyefisheyetrick10
wrapper.ping.timeout=300                       (see also Error "JVM appears hung" in wrapper.log)

# Display name of the service
wrapper.ntservice.displayname=freedumbytes.dev.net FishEyetrick11

# Description of the service
wrapper.ntservice.description=FishEye gives Git, Subversion and CVS a Web interface.trick12

Register the FishEye service from folder cd /d %FISHEYE_HOME% in an elevated command prompt: wrapper\bin\Fisheye-Install-NTService.bat. Start FishEye with net start fisheye.

Note

In case of an upgrade sc delete fisheye first (see also Section 1.1.5, “Task Manager replacement” in case of The specified service has been marked for deletion.).

Important

In case of a new jdk installation use an elevated command prompt just run net stop fisheye and net start fisheye. Verify the upgrade at http://freedumbytes.dev.net/fisheye/admin/sysinfo.do.

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”)

11.3.5.1. Log On Windows user

For the same reason as Section 8.1.3.1, “Log On Windows user” launch the Service Management Console with services.msc. Right click on freedumbytes.dev.net FishEye and select PropertiesLog On to use This account .\Tomcat. After password conformation click Apply and restart the service.

11.3.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 all privileges 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.36] and add the driver mysql-connector-java-5.1.36-bin.jar from the archive mysql-connector-java-5.1.36.zip to the FishEye classpath placing it into P:\dev\data\vcs\fisheye\lib. For older versions of FishEye remove the one that is already in P:\dev\apps\vcs\fecru-3.9.1\lib\dbdrivers\mysql. Requires a restart of FishEye to locate this new jar.

Connect to the FishEye Admin GUI http://freedumbytes.dev.net/fisheye/admin/ 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.

  • Minimum Pool Connections: 5.

  • Maximum Pool Connections: 20.

  • Parameters:

    • useUnicode=true

    • characterEncoding=UTF8

    • connectionCollation=UTF8_bin

  • Test Connection and click Save & Migrate.

11.3.7. Repository Settings

Connect to the FishEye Admin GUI http://freedumbytes.dev.net/fisheye/admin/ and configure 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@freedumbytes.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: 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.

To activate a repository select for example Repositoriesdpl-manualSummary and ActionsEnableStartSave.

11.3.8. User profile

On the Dashboard page click on the logged-in user at the top right of the menu bar and select Settings to edit for example:

  • Display Settings.

  • Profile & Email.

    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 jene.jasper@company.org.

  • Author Mapping and Add for CVS the commiter: %USERDOMAIN%\jjasper.

Chapter 12. Issue Tracker

12.1. JIRA

JIRA is a bug tracking, issue tracking, and project management application.

12.1.1. Resources

12.1.2. JIRA installation guide

Download the archive from All JIRA Download Options: atlassian-jira-6.4.11.zip [version 6.4.11].

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

Important

As of JIRA 4.3 'in-place database upgrades' is officially supported.

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

12.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 collate utf8_bin;
mysql> grant all privileges 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.36] and add the driver mysql-connector-java-5.1.36-bin.jar from the archive mysql-connector-java-5.1.36.zip to the JIRA classpath placing it into P:\dev\apps\issue\atlassian-jira-6.4.11-standalone\lib. For older versions of JIRA remove the one that is already there.

Create the JIRA database connection information in P:\dev\data\issue\jira\dbconfig.xml (see also Tuning Database Connections):

<?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&amp;connectionCollation=UTF8_bin</url>
    <driver-class>com.mysql.jdbc.Driver</driver-class>
    <username>jira-user</username>
    <password>password</password>
    <pool-min-size>20</pool-min-size>
    <pool-max-size>20</pool-max-size>
    <pool-max-wait>30000</pool-max-wait>
    <pool-max-idle>20</pool-max-idle>
    <pool-remove-abandoned>true</pool-remove-abandoned>
    <pool-remove-abandoned-timeout>300</pool-remove-abandoned-timeout>
    <validation-query>select 1</validation-query>
    <min-evictable-idle-time-millis>60000</min-evictable-idle-time-millis>
    <time-between-eviction-runs-millis>300000</time-between-eviction-runs-millis>
    <pool-test-while-idle>true</pool-test-while-idle>
    <validation-query-timeout>3</validation-query-timeout>
  </jdbc-datasource>
</jira-database-config>

12.1.3. JIRA configuration

Edit the data directory by changing the following property 1 in the P:\dev\apps\issue\atlassian-jira-6.4.11-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 /d P:\dev\apps\issue\atlassian-jira-6.4.11-standalone and running bin\startup.bat.

Verify that the server is running in your browser at http://localhost:8063. The Server ID for this JIRA instance is required to retrieve a new license from my.atlassian.com.

12.1.3.1. Required settings

You should see the JIRA setup wizard:

  1. Application Properties:

    • Application Title: freedumbytes.dev.net JIRA.

    • Mode: Private.

    • Base URL: http://freedumbytes.dev.net/jira and click Next.

    • Automated Backups: Disable Automated Backups. TODO

  2. Specify Your License Key:

  3. Set Up Administrator Account:

    • Fullname: JIRA Administrator.

    • Email: jira.admin@company.org.

    • Username: admin.

    • Password: password.

    • Confirm Password: password and click Next.

  4. Set Up Email Notifications:

    • Configure Email Notifications: Now.

    • Name: JIRA SMTP Server.

    • From address: jira.noreply@company.org.

    • Email prefix: [JIRA].

    • Server Type: SMTP Host.

    • Service Provider: Custom.

    • Host Name: mail.freedumbytes.dev.net.

    • Protocol: SMTP.

    • SMTP Port: 25.

    • Username: leave empty.

    • Password: leave empty and click Finish.

12.1.3.2. User, groups & roles

User Management 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 Default Settings 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.

12.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-6.4.11-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
      redirectPort="8443" enableLookups="false" 
      protocol="AJP/1.3" URIEncoding="UTF-8" />
        -->  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>
#  ProxyPass /jira        ajp://localhost:8064/jira
#  ProxyPassReverse /jira ajp://localhost:8064/jira

  ProxyPass /jira        http://localhost:8063/jira
  ProxyPassReverse /jira http://localhost:8063/jira

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

When JIRA and the Apache HTTP Server are restarted you should be able to browse JIRA at http://freedumbytes.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.

12.1.4.1. Privacy Policy

Next configure if Analytics collects data about the usage of JIRA and sends it to Atlassian (see the privacy policy for details).

12.1.5. Windows service

To restart automatically on Microsoft Windows create a service using an elevated command prompt as follows:

cd /d P:\dev\apps\issue\atlassian-jira-6.4.11-standalone

rename bin\tomcat7.exe tomcat7.exe.x86
rename bin\apr\tcnative-1.dll tcnative-1.dll.x86
rename bin\tomcat7.exe.x64 tomcat7.exe
rename bin\apr\tcnative-1.dll.x64 tcnative-1.dll

set JAVA_HOME=P:\dev\apps\prg\java-x64\jdk1.8.0_121
set CATALINA_HOME=P:\dev\apps\issue\atlassian-jira-6.4.11-standalone
bin\service.bat install jira

bin\tomcat7.exe //US//jira --DisplayName="freedumbytes.dev.net JIRA" ^
  --Description="JIRA - Issue tracking and project management." ^
  --Startup=auto

bin\tomcat7.exe //US//jira --JvmMx=768 --JvmMs=256 ^
  ++JvmOptions=-Djava.awt.headless=true;-Datlassian.standalone=JIRA

bin\tomcat7.exe //US//jira ++JvmOptions=-Dmail.mime.decodeparameters=true

Start it with net start jira.

Note

In case of an upgrade sc delete jira first (see also Section 1.1.5, “Task Manager replacement” in case of The specified service has been marked for deletion.).

Tip

As an alternative to change the additional settings of the JIRA service run: P:\dev\apps\issue\atlassian-jira-6.4.11-standalone\bin\tomcat7w.exe //ES//jira such as JavaJava Virtual Machine P:\dev\apps\prg\java\jdk1.8.0_121\jre\bin\server\jvm.dll.

Important

In case of a new jdk installation just run P:\dev\apps\issue\atlassian-jira-6.4.11-standalone\bin\tomcat7.exe //US//jira --Jvm auto (when JAVA_HOME is still pointing to the 64-bit version; see also Section 8.1.3.2, “Tomcat Manager”).

Verify the installation and the JVM memory usage at http://freedumbytes.dev.net/jira/secure/admin/ViewSystemInfo.jspa.

12.1.5.1. Log On Windows user

For the same reason as Section 8.1.3.1, “Log On Windows user” launch the Service Management Console with services.msc. Right click on freedumbytes.dev.net JIRA and select PropertiesLog On to use This account .\Tomcat. After password conformation click Apply and restart the service.

12.1.6. Global settings

System menu:

  • Select General Configuration and click Edit Settings:

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

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

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

Issues menu:

  • Under Issue Types select Sub-Tasks and Enable Sub-Tasks.

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

12.1.8. FishEye integration

12.1.8.1. Integration users

To auto-add the jira user (see also Section 7.1.4.1, “Authentication, authorization and access control”) in FishEye just login with that user at http://freedumbytes.dev.net/fisheye/ and logout again.

Optionally at the FishEye Admin GUI http://freedumbytes.dev.net/fisheye/admin/ select the User SettingsUsers and Edit user jira:

  • Display name: JIRA Integration.

  • Email: jira-integration@company.org and click Apply.

Next at the JIRA Admin GUI http://freedumbytes.dev.net/jira/secure/admin/user/UserBrowser.jspa Create User:

  • Username: fisheye.

  • Password: password.

  • Confirm: password.

  • Full Name: FishEye Integration.

  • Email: fisheye-integration@company.org and click Create.

12.1.8.3. FishEye plugin upgrade

At the FishEye Admin GUI http://freedumbytes.dev.net/fisheye/admin/ select the Systems SettingsManage Add-ons to filter Action required and just Update or Update All.

Next at the JIRA Admin GUI Add-ons http://freedumbytes.dev.net/jira/plugins/servlet/upm#manage filter Manage add-ons that have Action required and just Update or Update All.

12.1.9. User profile

On the Dashboard page click on the logged-in user at the top right of the menu bar and select Profile to edit for example:

  • Preferences.

  • Navigator Columns.

Chapter 13. Repository Manager

13.1. Nexus

Nexus is a Maven repository manager, created to provide reliable access to artifacts required for development and provisioning.

13.1.1. Resources

13.1.2. Nexus installation guide

Download the archive: nexus-2.11.4-01-bundle.zip [version 2.11.4-01].

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

trickPress +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.11.4-01 and P:\dev\data\repo\maven\nexus.

13.1.2.1. HTTP Binding

Configure the container for Nexus 2-3 in the Plexus property file P:\dev\apps\repo\nexus-2.11.4-01\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

13.1.3. Windows service

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

Edit the following entries 1-10 in the service wrapper configuration file P:\dev\apps\repo\nexus-2.11.4-01\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=javaP:\dev\apps\prg\java\jdk1.8.0_121\bin\javatrick1


# Additional JVM parameters (tune if needed, but match the sequence of numbers!)
#trick2wrapper.java.additional.1=-XX:MaxPermSize=192mtrick3
wrapper.java.additional.21trick2=-Djava.io.tmpdir=./tmp
#trick2wrapper.java.additional.3=-Djava.net.preferIPv4Stack=true
wrapper.java.additional.42trick2=-Dcom.sun.jndi.ldap.connect.pool.protocol="plain ssl"
wrapper.java.additional.42trick2.stripquotes=TRUE
#wrapper.java.additional.5=-Xdebug
#wrapper.java.additional.6=-Xnoagent
#wrapper.java.additional.7=-Djava.compiler=NONE
#wrapper.java.additional.8=-Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8000
#wrapper.java.additional.9=-XX:+HeapDumpOnOutOfMemoryError
wrapper.java.additional.3=-Xms128mtrick4
wrapper.java.additional.4=-Xmx1024mtrick5
#wrapper.java.additional.5=-Xrstrick6 see also Section 3.1.3.1, “Standard Edition Tools Reference”

 …

# Size Java memory, in MB (-Xms)
#trick2wrapper.java.initmemory=256
# Size Java memory, in MB (-Xmx). 
# This option only supports a setting up to 4000 (4Gb).
# If you need more, comment this option out 
# and use an explicit wrapper.java.additional option with -Xmx
#trick2wrapper.java.maxmemory=768

 …

# Set up JSW Console
wrapper.console.title=Sonatype Nexusfreedumbytes.dev.net Nexustrick7
 …

# Set up JSW as NT Service (unused on other OSes)
wrapper.ntservice.name=nexus-webappnexustrick8
wrapper.ntservice.displayname=freedumbytes.dev.net Nexustrick9
wrapper.ntservice.description=Nexus is a Maven repository manager.trick10

Register the Nexus service with the command in an elevated command processor: %NEXUS_HOME%\bin\nexus.bat install. Start Nexus with net 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.

Note

In case of an upgrade sc delete nexus first (see also Section 1.1.5, “Task Manager replacement” in case of The specified service has been marked for deletion.).

Important

In case of a new jdk installation use an elevated command prompt just run net stop nexus and net start nexus. Verify the upgrade at http://localhost:8067/nexus/#supporttools.

13.1.3.1. Log On Windows user

For the same reason as Section 8.1.3.1, “Log On Windows user” launch the Service Management Console with services.msc. Right click on freedumbytes.dev.net Nexus and select PropertiesLog On to use This account .\Tomcat. After password conformation click Apply and restart the service.

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

<VirtualHost *:80>
   …

  <IfModule proxy_module>
  <IfModule proxy_http_module>
     …

    <Proxy *>
      …
    </Proxy>

    # Nexus
    Include ../apache-conf/httpd-nexus.conftrick1
  </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>
  <IfModule proxy_module>
  <IfModule proxy_http_module>
    ProxyPass /nexus        http://localhost:8067/nexus
    ProxyPassReverse /nexus http://localhost:8067/nexus
  </IfModule>
  </IfModule>

  <Location /nexus>
    <RequireAll>
      Include ../apache-conf/httpd-lan-access.conf
    </RequireAll>
  </Location>
</IfModule>
</IfModule>

When the Apache HTTP Server is restarted you should be able to browse Nexus at http://freedumbytes.dev.net/nexus.

13.1.5. Nexus configuration

13.1.5.1. Users

Log In with the admin and default password admin123. 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 admin and deployment user to Set Password and Log Out.

To add additional (admin) users. Select SecurityUsersAdd…Nexus User:

  • User ID: jjasper.

  • First Name: Jene.

  • Last Name: Jasper.

  • Email: jjasper@company.org.

  • Status: Active.

  • New Password and Confirm Password.

  • Role Management: Add and for example check Nexus Administrator Role and click OK followed by Save.

13.1.5.2. Server Administration

Log In with the admin and the new password. Select AdministrationServer.

Configure the SMTP Settings:

  • Hostname: mail.freedumbytes.dev.net.

  • Port: 25.

  • Username: leave blank.

  • Password: leave blank.

  • System Email: nexus.noreply@company.org.

Enable Application Server Settings:

  • Base URL: http://freedumbytes.dev.net/nexus and click Save.

13.1.5.3. Capabilities

Optionally select AdministrationCapabilities (see also Configuring Repository Health Check and Accessing and Configuring Capabilities).

Configure the Health Check ConfigurationSettings:

  • Enabled: Checked.

  • Configure for all proxy repositories: Checked.

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

13.1.5.4.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 from the Available Repositories in Ordered Group Repositories and click Save.

For the Public Repositories on the Configuration tab remove Apache Snapshots from the Ordered Group Repositories and click Save.

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

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

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

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

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

13.1.5.5.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: 1.

  • Snapshot retention (days): 7.

  • Remove if released: Checked.

  • Grace period after release (days) : 5.

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

  • Name: Cleanup unused items.

    Note

    But uncheck Enable for now.

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

  • Alert Email : nexus.task@company.org.

  • Recurrence: Daily.

  • Start Date: Today.

  • Recurring Time: 22:30 and click Save.

13.1.6. Maven integration

13.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.3.9\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://freedumbytes.dev.net/nexus/content/groups/public-snapshots
      </url>
    </mirror>
    <mirror>
      <id>nexus-central</id>
      <mirrorOf>*trick2</mirrorOf>
      <url>http://freedumbytes.dev.net/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.3.9\conf\settings.xml:

  <profiles>
    <profile>
      <id>developmenttrick1</id>
      <repositories>
        <repository>
          <id>central.dev.net</id>
          <url>
            http://freedumbytes.dev.net/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://freedumbytes.dev.net/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.3.9\conf\settings.xml:

  <profiles>
     …

    <profile>
      <id>public-snapshots</id>
      <repositories>
        <repository>
          <id>public-snapshots.dev.net</id>
          <url>
            http://freedumbytes.dev.net/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://freedumbytes.dev.net/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.

13.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://freedumbytes.dev.net/nexus/content/repositories/releases</url>
    </repository>
    <snapshotRepository>
      <id>nexus-snapshots</id> <!-- (see 2) -->
      <name>Internal Snapshots</name>
      <url>http://freedumbytes.dev.net/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.3.9\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.6, “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.

13.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://freedumbytes.dev.net/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.

Chapter 14. Continuous Integration

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

14.1.1. Resources

14.1.2. Jenkins installation guide

Download the latest archive: jenkins.war [version 1.648].

trickPress +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-8.0.26\webapps.

Note

Stop Tomcat service when Jenkins doesn't restart properly because the P:\dev\apps\webserver\apache-tomcat-8.0.26\webapps\jenkins could not be cleaned completely. After Tomcat is stopped just delete the folder webapps\jenkins and restart Tomcat service.

14.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 one for the Log On Windows user with a copy of 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.

14.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>
  AllowEncodedSlashes NoDecodetrick1
  ProxyPass /jenkins        ajp://localhost:8069/jenkins nocanontrick1
  ProxyPassReverse /jenkins ajp://localhost:8069/jenkins

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

Note

The entries at 1 are required to suppress the message It appears that your reverse proxy set up is broken. on the Manage Jenkins page.

When the Apache HTTP Server is restarted you should be able to browse Jenkins at http://freedumbytes.dev.net/jenkins.

14.1.4. Jenkins configuration

14.1.4.1. System

Select JenkinsManage JenkinsConfigure Global Security or type config in the search box to set:

trickSelect JenkinsManage JenkinsConfigure System or type config in the search box to set:

  • # of executors: 6 (where a good value to start with would be the number of processors on your system).

  • Quiet period: 30.

  • SCM checkout retry count: 3.

  • Add Ant installation:

    • Name: ANT_HOME.

    • Disable Install automatically.

    • ANT_HOME: P:\dev\apps\build\apache-ant-1.9.6.

  • Add Maven installation:

    • Name: M2_HOME.

    • Disable Install automatically.

    • MAVEN_HOME: P:\dev\apps\build\apache-maven-3.3.9.

  • Maven Project Configuration:

    • Optionally disable Help make Jenkins better by sending anonymous usage statistics and crash reports to the Jenkins project.

  • Jenkins Location:

    • Jenkins URL: http://freedumbytes.dev.net/jenkins/.

    • System Admin e-mail address: jenkins.noreply@company.org.

  • E-mail Notification:

    • SMTP server: mail.freedumbytes.dev.net.

    • Default user e-mail suffix: @company.org and click Save.

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

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

  • Dashboard View provides a portal-like view for the Jenkins instance.

  • Modern Status provides an alternative set of status and action icons to provide a fresh look to Jenkins and to be friendly for all users i.e. iconic not just color indication.

  • Build Trigger Badge displays icon representing the cause of a build directly in the build history. It lets you quickly know which cause triggered a build.

  • Timestamper adds timestamps to the Console Output with the option to switch to between System clock time and Elapsed time.

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

  • Git allows use of Git as a build SCM.

  • JIRA integration (see also Section 14.1.5, “JIRA integration”).

  • Configuration Slicing to perform mass configuration of select project properties, including email, timer, discard old builds, and Maven configuration.

  • Obsolete SonarQube Scanner integration (see also Section 17.2.8, “Jenkins integration”).

After successful Install of all selected plugins reload Jenkins at http://freedumbytes.dev.net/tomcat/manager/html for the latest version of the plugin to show up in the Installed tab.

Note

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

14.1.4.2.1. Configure Plugins

Select JenkinsManage JenkinsConfigure System or type config in the search box to set:

  • Dependency Graph Viewer Configuration:

    • Check Enable rendering with graphviz.

    • Dot Executable Path: P:\dev\apps\editor\graphviz\bin\dot.exe.

14.1.4.3. Subversion authentication

Setup Subversion authentication in Jenkins at http://freedumbytes.dev.net/jenkins/scm/SubversionSCM/enterCredential:

  • Repository URL: http://freedumbytes.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.

    Or alternatively use credentials (see also Section 14.1.4.4, “Git authentication”):

14.1.4.4. Git authentication

For Git authentication by Jenkins look at _netrc setup in Section 8.1.3.1.1, “netrc” or select JenkinsManage JenkinsManage Credentials and Add CredentialsUsername with password:

  • Scope: Global.

  • Username: jenkins.

  • Password: password.

  • Description: apache proxy user and click Save.

14.1.5. JIRA integration

JIRA Plugin for Jenkins and Jenkins Plugin for JIRA integrate Jenkins and Hudson/Jenkins CI Servers with JIRA to display builds in JIRA.

14.1.5.1. Jenkins Plugin installation guide

Download the archive: jenkins-jira-plugin-1.4.5.hpi [version 1.4.5].

Just drop the downloaded *.hpi or *.jpi file into the P:\dev\data\ci\jenkins\plugins directory and rename to jenkins-jira-plugin.hpi. You will then need to restart Jenkins (many containers let you do this without restarting the container).

Next at the JIRA Admin GUI Add-ons http://freedumbytes.dev.net/jira/plugins/servlet/upm/marketplace/featured Find new add-ons with Search the Marketplace for jenkins and just Install.

Note

In case of an issue (see also JJI-134) with the latest version download an older *.obr version and select Add-onsManage add-onsUpload add-on to install this prior version.

14.1.6. Slave configuration

A butler is a domestic worker in a large household. A valet is a servants who serve as personal attendants to their employer.

Select JenkinsManage JenkinsManage Nodes to add:

  • New Node with:

    • Node name: jeeves.

    • As Dumb Slave and click OK.

Configure this new node as follows:

  • # of executors: 6 (where a good value to start with would be the number of processors on your system).

  • Remote root directory: P:\dev\data\ci\jeeves.

  • Labels: windows.

  • Usage: Utilize this node as mush as possible.

  • Launch method: Launch slave agents via Java Web Start.

  • Availability: Keep this slave on-line as much as possible and click Save.

Select JenkinsBuild Executor Statusjeeves to connect the slave to Jenkins using Launch agent from browser on slave by clicking the orange Launch button. This will download the file slave-agent.jnlp. To install the slave jeeves run this file and supply proxy credentials:

  • User name: jjasper.

  • Password: password.

  • Labels: windows.

  • Leave Save this password in your password list unchecked and click OKRunFileInstall as a service.

Note

Don't forget to create the slave folder first with mkdir P:\dev\data\ci\jeeves.

Edit the generated id 1 and name 2 in P:\dev\data\ci\jeeves\jenkins-slave.xml to insert /tomcat :

<service>
  <id>jenkinsslave-P__dev_data_ci_jeevestrick1</id>
  <name>Jenkins Slavefreedumbytes.dev.net Jeevestrick2</name>
  <description>
   This service runs a slave for Jenkins continuous integration system.
  </description>
  <executable>P:\dev\apps\prg\java\jre1.8.0_121\bin\java.exe</executable>
  <arguments>
    <!-- -Xrs see also Section 3.1.3.1, “Standard Edition Tools Reference” -->
    -jar "%BASE%\slave.jar" -jnlpUrl 
    http://freedumbytes.dev.net/jenkins/computer/jeeves/slave-agent.jnlp 
    -secret …
  </arguments>
  <logmode>rotate</logmode>
  <onfailure action="restart" />
</service>

To activate the changes reinstall the service with the following commands in an elevated command processor (see also Section 1.1.5, “Task Manager replacement” in case of WMI.WmiException: ServiceMarkedForDeletion):

cd /d P:\dev\data\ci\jeeves
jenkins-slave.exe stop
jenkins-slave.exe uninstall
del *.log
jenkins-slave.exe install
jenkins-slave.exe start
services.msc

Important

In case of a new jdk installation use an elevated command prompt just run net stop jeeves and net start jeeves. Verify the upgrade at http://freedumbytes.dev.net/jenkins/computer/jeeves/systemInfo.

Note

The jdk upgrade for Jenkins master is handled when the upgrade is done for Tomcat and can be verified at http://freedumbytes.dev.net/jenkins/systemInfo.

Next fix the following error in P:\dev\data\ci\jeeves\jenkins-slave.err.log:

Failing to obtain http://freedumbytes.dev.net/jenkins/computer/jeeves/slave-agent.jnlp?encrypt=true
  java.io.IOException: Failed to load …: 401 Unauthorized
    at hudson.remoting.Launcher.parseJnlpArguments(Launcher.java:275)
    at hudson.remoting.Launcher.run(Launcher.java:219)
    at hudson.remoting.Launcher.main(Launcher.java:192)
Waiting 10 seconds before retry

Which is also displayed in http://freedumbytes.dev.net/jenkins/computer/jeeves/ node page as Connection was broken and P:/dev/logs/httpserver/freedumbytes.dev.net-access.log:

[201605 01:11:16] "GET /jenkins/computer/jeeves/slave-agent.jnlp?encrypt=true HTTP/1.1" 401 381 "-" "Java/1.8.0_121"

Just allow anonymous access for the local area network by editing P:\dev\apps\httpserver\apache-conf\httpd-jenkins.conf:

<IfModule proxy_module>
<IfModule proxy_ajp_module>
  …

  <Location /jenkins>
    Include ../apache-conf/httpd-freedumbytes-realm.conf
  </Location>

  <Location /jenkins/git/notifyCommit>
    <RequireAll>
      Include ../apache-conf/httpd-lan-access.conf
    </RequireAll>
  </Location>

  <Location /jenkins/computer/jeeves/slave-agent.jnlp>trick1
    <RequireAll>
      Include ../apache-conf/httpd-lan-access.conftrick2
    </RequireAll>
  </Location>
</IfModule>
</IfModule>

After restarting jeeves fix the next error in P:\dev\data\ci\jeeves\jenkins-slave.err.log:

May 07, 2016 1:25:28 AM hudson.remoting.jnlp.Main createEngine
INFO: Setting up slave: jeeves
May 07, 2016 1:25:28 AM hudson.remoting.jnlp.Main$CuiListener <init>
INFO: Jenkins agent is running in headless mode.
May 07, 2016 1:25:28 AM hudson.remoting.jnlp.Main$CuiListener status
INFO: Locating server among [http://freedumbytes.dev.net/jenkins/]
May 07, 2016 1:25:28 AM hudson.remoting.jnlp.Main$CuiListener error
SEVERE: http://freedumbytes.dev.net/jenkins/tcpSlaveAgentListener/ is invalid: 401 Unauthorized
  java.lang.Exception: …/tcpSlaveAgentListener/ is invalid: 401 Unauthorized
    at hudson.remoting.Engine.run(Engine.java:215)

See also P:/dev/logs/httpserver/freedumbytes.dev.net-access.log:

[20160507 01:25:27] "GET …/computer/jeeves/slave-agent.jnlp?encrypt=true HTTP/1.1" 200 736 "-" "Java/1.8.0_121"
[20160507 01:25:28] "GET …/tcpSlaveAgentListener/ HTTP/1.1" 401 381 "-" "Java/1.8.0_121"

Again allow anonymous access for the local area network by editing P:\dev\apps\httpserver\apache-conf\httpd-jenkins.conf:

<IfModule proxy_module>
<IfModule proxy_ajp_module>
  …

  <Location /jenkins/computer/jeeves/slave-agent.jnlp>
    <RequireAll>
      Include ../apache-conf/httpd-lan-access.conf
    </RequireAll>
  </Location>

  <Location /jenkins/tcpSlaveAgentListener>trick1
    <RequireAll>
      Include ../apache-conf/httpd-lan-access.conf
    </RequireAll>
  </Location>
</IfModule>
</IfModule>

Now after restarting jeeves check P:\dev\data\ci\jeeves\jenkins-slave.err.log:

May 07, 2016 1:38:02 AM hudson.remoting.jnlp.Main createEngine
INFO: Setting up slave: jeeves
May 07, 2016 1:38:02 AM hudson.remoting.jnlp.Main$CuiListener <init>
INFO: Jenkins agent is running in headless mode.
May 07, 2016 1:38:02 AM hudson.remoting.jnlp.Main$CuiListener status
INFO: Locating server among [http://freedumbytes.dev.net/jenkins/]
May 07, 2016 1:38:02 AM hudson.remoting.jnlp.Main$CuiListener status
INFO: Handshaking
May 07, 2016 1:38:02 AM hudson.remoting.jnlp.Main$CuiListener status
INFO: Connecting to freedumbytes.dev.net:49403
May 07, 2016 1:38:02 AM hudson.remoting.jnlp.Main$CuiListener status
INFO: Trying protocol: JNLP2-connect
May 07, 2016 1:38:02 AM hudson.remoting.jnlp.Main$CuiListener status
INFO: Connected

See also P:/dev/logs/httpserver/freedumbytes.dev.net-access.log:

[20160507 01:38:01] "GET …/computer/jeeves/slave-agent.jnlp?encrypt=true HTTP/1.1" 200 736 "-" "Java/1.8.0_121"
[20160507 01:38:02] "GET …/tcpSlaveAgentListener/ HTTP/1.1" 200 12 "-" "Java/1.8.0_121"

Note

And access to slave-agnet-jnlp is still not possible without the secret code:

trick
Jenkins Slave Agent
Figure 14.1. Jenkins Slave Agent

Optionally select JenkinsManage JenkinsManage Nodes to change:

  • masterConfigure with:

    • # of executors: 2.

    • Labels: master.

    • Usage: Only build jobs with label restrictions matching this node and click Save.

Historically, Jenkins master and slaves behaved as if they altogether form a single distributed process. This means a slave can ask a master to do just about anything within the confinement of the operating system, such as accessing files on the master or trigger other jobs on Jenkins. Should you use Slave To Master Access Control JenkinsManage JenkinsConfigure Global Security and check Enable Slave → Master Access Control.

14.1.6.1. Log On Windows user

For the same reason as Section 8.1.3.1, “Log On Windows user” launch the Service Management Console with services.msc. Right click on freedumbytes.dev.net Jeeves and select PropertiesLog On to use This account .\Tomcat. After password conformation click Apply and restart the service.

Chapter 15. Integrated Development Environment

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

15.1.1. Resources

15.1.2. Eclipse installation guide

Download the archive: eclipse-jee-mars-2-win32-x86_64.zip [version 4.5.2].

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

Now rename P:\dev\apps\ide\eclipse to P:\dev\apps\ide\eclipse-4.5.2.

trickConfigure the vm settings (and windows processes) 1-2 in P:\dev\apps\ide\eclipse-4.5.2\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-x64/jdk1.8.0_121/jre/bin/server/jvm.dlltrick2
--launcher.appendVmargs
-vmargs
-Dosgi.requiredJavaVersion=1.7
-Xms256m
-Xmx1024m

Note

Or when upgrading just run p:\dev\apps\editor\winmerge\WinMergeU.exe P:\dev\apps\ide\eclipse-4.5.2\eclipse.ini P:\dev\apps\ide\eclipse-4.5.1.

Initialize the Eclipse configuration with P:\dev\apps\ide\eclipse-4.5.2\eclipse.exe -initialize.

Configure the user's area and the default workspace in P:\dev\apps\ide\eclipse-4.5.2\configuration\config.ini:

osgi.instance.area.default=@user.home/workspaceC\:/workspace-4.5.2trick1

For ease of use create a shortcut on the Quick Launch Toolbar by dragging eclipse.exe from P:\dev\apps\ide\eclipse-4.5.2 onto it. Click this shortcut to start Eclipse with this now default Workspace at C:\workspace-4.5.2.

15.1.3. Eclipse upgrading

trick
Eclipse Updates Available
Figure 15.1. Eclipse Updates Available

Tip

In case of a newer version of the Eclipse IDE itself create copies of the prior one to for example P:\dev\apps\ide\eclipse-4.5.2 and also its workspace to C:\workspace-4.5.2. Edit any shortcut on the Quick Launch Toolbar according. Click this shortcut to start Eclipse and switch to the new default Workspace at C:\workspace-4.5.2.

trick
Eclipse prior version
Figure 15.2. Eclipse prior version

Click on the Updates Available popup or:

  • Select HelpCheck for Updates:

    trick
    Eclipse Available Updates
    Figure 15.3. Eclipse Available Updates

  • Check the ones that must be installed 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

    A second restart of Eclipse is necessary to show to latest splash screen:

    trick
    Eclipse latest version
    Figure 15.4. Eclipse latest version

Note

To revert an installation select HelpAbout EclipseInstallation DetailsInstallation History and move from Current Installation down and click Revert.

trick
Eclipse Installation History
Figure 15.5. Eclipse Installation History

15.1.4. 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 freedumbytes.dev.net. Export those Clean Up settings as eclipse.codestyle.cleanup.xml.

  • Select Formatter and click Edit for Active profile: Eclipse [built-in] to roll your own Profile name freedumbytes.dev.net. Export the Formatter settings as eclipse.codestyle.formatter.xml.

    Tip

    To turn the formatter off and on use @formatter:off and @formatter:on.

  • Select Organize Imports and click New for the company package net.dev.freedumbytes. Export the Organize Import settings as eclipse.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.

Important

Unless you are going to use Lombok then select Format source codeFormat all lines (and just use aforementioned @formatter) to avoid ArrayIndexOutOfBoundsException: -1 during CleanUpPostSaveListener on Ctrl+S.

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.

Optionally select WindowPreferences and type filter text typing and uncheck Tab key adjusts the indentation of the current line for Editor for Java and JavaScript. Don't forget to Apply the changes.

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

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

Tip

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 (unless you are going to use Lombok) 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.

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

    Tip

    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, JavaScript Search, Plug-in Search and Remote Search (that option 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.

15.1.5. Plugins installation & configuration guide

Install the following plugins.

Note

Should a plugin Update Site only list an earlier version try the above described Eclipse upgrading option. This resulted in the latest version for BIRT (see also Section 15.1.5.8, “Memory Analyzer”).

It is also possible to search online at http://marketplace.eclipse.org/ and drag to install:

trick
Eclipse Marketplace Drag to Install
Figure 15.6. Eclipse Marketplace Drag to Install

15.1.5.1. Lombok

Project Lombok (features) to spice up your java by Reducing Boilerplate Code.

Download the archive: lombok.jar [version 1.16.8].

Copy this .jar file to P:\dev\apps\ide. Edit 1 in P:\dev\apps\ide\eclipse-4.5.2\eclipse.ini as follows:

 …
-vmargs
-Dosgi.requiredJavaVersion=1.7
-Xms256m
-Xmx1024m
-javaagent:P:/dev/apps/ide/lombok.jartrick1

Verify installation with HelpAbout Eclipse which should list Lombok now also.

Tip

When using Lombok the getters and setters are no longer available in the code. To be able to find references in the workspace (Ctrl+Shift+G) you are going to need the Outline view. To save space just drag it next to the Task List tab.

15.1.5.2. EGit

EGit [version 4.3.0] 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.

JGit [version 4.3.0] is the Java implementation of Git. It is a library, that also can be used in your own applications. It also provides some sort of CLI operations. EGit on the other side is the Eclipse team provider plugin for Git, which uses JGit as Git implementation. Simplified you could say EGit is the UI part, and JGit the background part. JGit doesn't depend on EGit, but EGit does depend on JGit.

Install the plugin EGit in Eclipse:

  • Select HelpInstall New Software….

  • Add… the Location http://download.eclipse.org/egit/updates/ with Name EGit P2 Repository and click Ok.

  • Select to Work with: EGit Update Site - http://download.eclipse.org/egit/updates/.

  • Select the following components:

    • Eclipse Git Team Provider [4.3.0]

    • Eclipse Git Team Provider - Task focused interface [4.3.0]

    • Command Line Interface for Java implementation of Git [4.3.0]

    • Java implementation of Git [4.3.0]

    • Java implementation of Git - optional Http support using Apache httpclient [4.3.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

Should the Commit Message in the Git Staging view not match with the curent Mylyn Task just copy its details:

trick
Eclipse Mylyn Task List view
Figure 15.7. Eclipse Mylyn Task List view

after that paste the correct details:

trick
Eclipse EGit Staging view
Figure 15.8. Eclipse EGit Staging view

15.1.5.2.1. EGit configuration

Set the following preferences at WindowPreferences:

  • Select TeamGit and as Default Repository folder enter C:\dev\projects and click OK.

15.1.5.3. Subclipse

Subclipse [version 1.10.13] 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.10.x/ with Name Subclipse 1.10.x Update Site and click Ok.

  • Select to Work with: Subclipse 1.10.x Update Site - http://subclipse.tigris.org/update_1.10.x/.

  • Select the following components:

    • CollabNet Merge Client [4.1.0]

    • Subclipse (Required) [1.10.13]

    • Subclipse Integration for Mylyn 3.x (Optional) [3.0.0]

    • Subversion Client Adapter (Required) [1.10.3]

    • Subversion JavaHL Native Library Adapter [1.8.15]

    • Subversion Revision Graph [1.1.1]

    • SVNKit Library [1.8.12]

    • JNA Library [4.1.0]

    • SVNKit Client Adapter (Not required) [1.8.9] 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.

15.1.5.3.1. Subclipse configuration

Set the following preferences at WindowPreferences:

  • Select TeamSVN and as SVN Interface Client choose SVNKit (Pure Java) and click OK.

15.1.5.4. Mylyn

Mylyn [version 3.19.0] 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….

  • Add… the Location http://download.eclipse.org/mylyn/releases/latest with Name Mylyn for Eclipse and click Ok.

  • Select to Work with: Mylyn for Eclipse - http://download.eclipse.org/mylyn/releases/latest.

  • Select the following components (uncheck Hide items that are already installed):

    • Mylyn Task List [3.19.0]

    • Mylyn Task-Focused Interface [3.19.0]

    • Mylyn WikiText [2.8.0]

    • Mylyn Builds Connector: Hudson/Jenkins [1.11.0]

    • Mylyn Context Connector: Eclipse IDE [3.19.0]

    • Mylyn Context Connector: Java Development [3.19.0]

    • Mylyn Context Connector: Plug-in Development [3.19.0]

    • Mylyn Context Connector: Team Support [3.19.0]

    • Mylyn Versions Connector: Subclipse [1.11.0]

    • Mylyn Versions Connector: Git [1.11.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.

For JIRA support:

  • Select HelpInstall New Software….

  • Add… the Location http://update.atlassian.com/atlassian-eclipse-plugin/rest/e3.7/ with Name Atlassian Connector for Eclipse and click Ok.

  • Select to Work with: Atlassian Connector for Eclipse - http://update.atlassian.com/atlassian-eclipse-plugin/rest/e3.7/.

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

Warning

We are discontinuing the support for Atlassian IDE Connectors (source and fork).

15.1.5.4.1. Mylyn configuration

Set the following WindowPreferencesMylyn:

  • In Tasks define:

    • Change Week Start to Monday.

    • Enable Track time spent within Eclipse when a task is active.

    • Optionally set Stop time accumulation after 15 minutes of inactivity.

  • In Team 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).

15.1.5.4.2. 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://freedumbytes.dev.net/jira.

  • Label: freedumbytes.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 Task Editor Settings: Confluence (default).

  • Validate Settings and click Finish and do not create a query yet.

Add queries to the freedumbytes.dev.net JIRA task repository by right clicking on it and selecting New Query…. Select Create query using form and click Next:

  • Query Title: freedumbytes.dev.net JIRA issues.

  • Assigned To: Current User and click Finish.

Note

The other issues, that are viewed in Eclipse, will show up in the category Uncategorized.

15.1.5.4.3. Jenkins integration

In the Builds view select Add Build Server…. Select Hudson (supports Jenkins) and click Next:

  • Server: http://freedumbytes.dev.net/jenkins.

  • Label: freedumbytes.dev.net Jenkins builds.

  • Keep: Anonymous checked.

  • Open Http Authentication and check Enable Http Authentication:

    • User ID: jjasper.

    • Password: password.

  • Validate and click Refresh for Build Plans.

  • Click Select All in Build Plans and click Finish.

Set the following WindowPreferences:

  • In MylynBuilds check Automatically refresh builds and click Apply.

15.1.5.5. Maven

Maven integration [version 1.6.2] 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 Update Site and click Ok.

  • Select to Work with: m2e Update Site - http://download.eclipse.org/technology/m2e/releases/.

  • Type filter text: m2e.

  • Select the following components:

    • m2e - Maven Integration for Eclipse (includes Incubating components) [1.7.0]

    • m2e - slf4j over logback logging (Optional) [1.7.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 Directory… to P:\dev\apps\prg\java-x64\jdk1.8.0_121 and click Finish. Now check this jdk1.8.0_121 and Remove the old jre1.x.x_xx and apply with OK (see also Section 15.1.2, “Eclipse installation guide”).

Caution

After upgrading maven-jar-plugin to 3.x Eclipse reports the following error org.apache.maven.archiver.MavenArchiver.getManifest(org.apache.maven.project.MavenProject, org.apache.maven.archiver.MavenArchiveConfiguration)

  • Select HelpInstall New Software….

  • Add… the Location https://otto.takari.io/content/sites/m2e.extras/m2eclipse-mavenarchiver/0.17.2/N/LATEST/ and click Ok.

  • Select the following components:

    • m2e connector for mavenarchiver pom properties [0.17.2] and click Next twice.

15.1.5.5.1. Maven configuration

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 11.2.3, “Global ignores” for Subversion.

  • In MavenInstallations:

    • Add… the latest Maven installation Directory…: P:\dev\apps\build\apache-maven-3.3.9 and click OK. Check this new Maven installation and click Apply.

  • Next in MavenUser Settings point to the corresponding Maven settings:

    • Global Settings: P:\dev\apps\build\apache-maven-3.3.9\conf\settings.xml.

  • In Maven:

    • Check Hide folders of physically nested modules (experimental) when using a git project (see also the note below).

    Important

    Using the option Hide folders of physically nested modules (experimental) can lead to merge conflicts messages in Team Synchronizing.

    Note

    As an alternative right-click on the submodule and select Properties or Alt+Enter to set the attribute Derived. Alas the Git Plugin will then mark the submodule as ignored in .gitignore. 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.

    Tip

    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… and click OK or use Alt+F5.

  • In MavenUser Interface:

    • Optionally check Open XML page in the POM editor by default and click OK.

For configuration of the lifecycle mappings see Section 16.1.13, “M2Eclipse lifecycle configuration”.

Occasionally Eclipse build fails with the error <path>/target/m2e-wtp/web-resources/META-INF/MANIFEST.MF (No such file or directory). Change the preferences at WindowPreferencesMavenJava EE IntegrationWAR Project preferences and uncheck Maven Archiver generates files under the build directory (see also M2E-WTP FAQ).

15.1.5.6. e(fx)clipse

e(fx)clipse [version 2.3.0] provides JavaFX tooling for the Eclipse IDE. Read more about the latest developments on BestSolution's specific blog.

Install the plugin e(fx)clipse in Eclipse:

  • Select HelpInstall New Software….

  • Add… the Location http://download.eclipse.org/efxclipse/updates-released/2.3.0/site/ with Name e(fx)clipse Update Site and click Ok.

  • Select to Work with: e(fx)clipse Update Site - http://download.eclipse.org/efxclipse/updates-released/2.3.0/site/.

  • Select the following components:

    • e(fx)clipse - IDE [2.3.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.

Note

This also should take care of Access restriction: … is not API (restriction on required library '…\jre\lib\ext\jfxrt.jar') messages.

15.1.5.7. JD-Eclipse

JD-Eclipse [version 1.0.0-RC2]allows you to display all the Java sources during your debugging process, even if you do not have them all.

Install the plugin JD-Eclipse in Eclipse:

  • Select HelpInstall New Software….

  • Add… the Location http://jd.benow.ca/jd-eclipse/update/ with Name JD-Eclipse Update Site and click Ok.

    Note

    For installation of a more recent version see also GitHub.

  • Select to Work with: JD-Eclipse Update Site - http://jd.benow.ca/jd-eclipse/update/.

  • Select the following components:

    • JD-Eclipse Plug-in [0.1.5] and click Next twice.

  • Choose I accept the terms of the license agreements after reading them and Finish.

  • To complete the installation restart Eclipse.

15.1.5.8. Memory Analyzer

BIRT [version 4.5.0] is an open source technology platform used to create data visualizations and reports that can be embedded into rich client and web applications.

Install the plugin BIRT in Eclipse to be able to use the optional Memory Analyzer Charts:

  • Select HelpInstall New Software….

  • Add… the Location http://download.eclipse.org/birt/update-site/4.4/ with Name BIRT Update Site and click Ok.

  • Select to Work with: BIRT Update Site - http://download.eclipse.org/birt/update-site/4.4/.

  • Select the following components:

    • BIRT Framework [4.4.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.

Memory Analyzer (MAT) [version 1.5.0] is a fast and feature-rich Java heap analyzer that helps you find memory leaks and reduce memory consumption.

Install the plugin Memory Analyzer in Eclipse:

  • Select HelpInstall New Software….

  • Add… the Location http://download.eclipse.org/mat/1.5/update-site/ with Name MAT Update Site and click Ok.

  • Select to Work with: MAT Update Site - http://download.eclipse.org/mat/1.4/update-site/.

  • Select the following components:

    • Memory Analyzer [1.5.0]

    • Memory Analyzer (Charts) [optional] [1.5.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.

Select WindowPerspectiveOpen perspectiveOther… Memory Analysis to analyze .hprof files.

VisualVM is a visual tool integrating several commandline JDK tools and lightweight profiling capabilities. Designed for both production and development time use, it further enhances the capability of monitoring and performance analysis for the Java SE platform. It is supplied with the JDK and can be run from the commandline with jvisualvm and used to create for example Thread and Heap dumps.

Or run an Java applications with the following options:

  • -XX:+HeapDumpOnOutOfMemoryError to enable the JVM to dump the Java heap in HPROF binary format (.hprof file) when an OutOfMemoryError error occurs.

  • -XX:HeapDumpPath=C:\dev\projects to specify the path and file name of the HPROF dump file.

15.1.5.9. Code Coverage

EclEmma [version 2.3.3] is a free Java code coverage tool for Eclipse.

Install the plugin EclEmma in Eclipse:

  • Select HelpInstall New Software….

  • Add… the Location http://update.eclemma.org/ with Name EclEmma and click Ok.

  • Select to Work with: EclEmma - http://update.eclemma.org/.

  • Select the following components:

    • EclEmma Java Code Coverage [2.3.3] and click Next twice.

  • Choose I accept the terms of the license agreements after reading them and Finish.

  • To complete the installation restart Eclipse.

Tip

Instead of using the shortcut Alt+Shift+X, T to Run As1 JUnit Test use the shortcut Alt+Shift+E, T to Coverage As1 JUnit Test. After its first usage a Coverage view appears in the tabs at the bottom of the screen. Optionally just drag it next to the Task List and Outline tabs.

trick
Eclipse EclEmma Code Coverage Plugin
Figure 15.9. Eclipse EclEmma Code Coverage Plugin

15.1.5.10. SonarLint

SonarLint [version 2.0.2] is an Eclipse plugin that provides on-the-fly feedback to developers on new bugs and quality issues injected into Java, JavaScript and PHP code.

Install the plugin SonarLint in Eclipse:

  • Select HelpInstall New Software….

  • Add… the Location http://eclipse.sonarlint.org/ with Name SonarLint for Eclipse Update Site and click Ok.

  • Select to Work with: SonarLint for Eclipse Update Site - http://eclipse.sonarlint.org/.

  • Select the following components:

    • SonarLint for Eclipse [2.0.2].

    • SonarLint for Eclipse Java Configuration Helper [2.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.

15.1.5.10.1. SonarLint configuration

In Java perspective configure the connection to SonarQube with WindowShow ViewOther… or shortcut Alt+Shift+Q, Q and from SonarLint select: SonarQube Servers.

In the SonarQube Servers view create the NewServer connection with:

  • Server URL: http://freedumbytes.dev.net/sonarqube.

  • Server Label: freedumbytes.dev.net SonarQube.

  • Username / Token: sonarlint (see also Section 17.2.4.3, “Users”).

  • Password: password and after Test connection click Finish.

Note

See also Section 17.2.5, “Apache configuration” about allowing anonymous access to SonarQube for SonarLint because it uses the /api to get the information:

"GET /api/system/status HTTP/1.1" 200 53 "-" "SonarLint Eclipse 2.0.2.20160427-0800-RELEASE"
"GET /api/plugins/installed HTTP/1.1" 200 2155 "-" "SonarLint Eclipse 2.0.2.20160427-0800-RELEASE"
"GET /api/authentication/validate?format=json HTTP/1.1" 200 14 "-" "SonarLint Eclipse 2.0.2.20160427-0800-RELEASE"

Now bind one or more Eclipse project(s) in a Working Set to their remote SonarQube pair. Right click on project(s) and select SonarLintBind to a SonarQube project...Auto bind selected projects and click Finish.

trick
Eclipse SonarLint Quality Issues Plugin
Figure 15.10. Eclipse SonarLint Quality Issues Plugin

15.1.6. Team support

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

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.

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.

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

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

Chapter 16. Project

Lets setup a base structure, for Maven projects to come, with the following JIRA project:

  • Maven Setup [MVNSTP]: Maven support components (see also repository branches/maven-setup).

    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.

    3. versions-rules: A ruleSet file containing the rules that control how to compare version numbers.

    4. lifecycle-mapping: Eclipse workspace project configuration and behaviour during Eclipse workspace build.

    and versions:

    • 3.0-beta - Base structure for Maven projects to come.

    • 3.1-beta - Quality Assurance with SonarQube.

    Important

    For the release procedure the version should end with -SNAPSHOT, but it is left out for the sake of consistency with the version of this document itself. And of course also because of inter-dependencies between for example Maven Setup and Maven Skins projects, which would require extra releases and thus different release roadmaps of those projects. Now for a proof of concept it is a simple mvn install to test out new features.

16.1. Setup base components

Start a new bare Git repository maven-setup by calling /p/dev/apps/windows/batch/git-create-repo.sh /p/dev/data/repo/git maven-setup.git "Maven support components" -jenkinsHook in Git Bash.

Clone this remote repository with the following command git-clone jjasper maven-setup.

Create the minimal POM in C:\dev\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>3.1-beta</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 C:\dev\projects\maven-setup and click Finish.

Note

To exclude the target directory from search actions and the like, right click on it and select PropertiesDerived.

Tip

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… and click OK or use Alt+F5.

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

16.1.2. Project information

Supply the project information in C:\dev\projects\maven-setup\pom.xml:

   <artifactId>setup</artifactId>
   <version>3.1-beta</version>
   <packaging>pom</packaging>
+
+  <name>Free Dumb Bytes Maven Setup</name>
+  <description>
+    Setup the site, license and plugin configuration files.
+  </description>
+  <url>${mavenHost}/maven-setup</url>
+  <inceptionYear>2010</inceptionYear>
+  <prerequisites>
+    <maven>3.3.9</maven>
+  </prerequisites>
+  <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>${organizationHost}</url>
+  </organization>
+  <developers>
+    <developer>
+      <id>jjasper</id>
+      <name>Jene Jasper</name>
+      <email>jjasper@dev.java.net</email>
+      <organization>Free Dumb Bytes</organization>
+      <organizationUrl>${organizationHost}</organizationUrl>
+      <roles>
+        <role>developer</role>
+      </roles>
+      <timezone>+1</timezone>
+      <properties>
+        <picUrl>${avatarHost}/avatar/jjasper?s=64&amp;noCache=true</picUrl>
+      </properties>
+    </developer>
+  </developers>
+
+  <contributors />
+
+  <mailingLists />
 </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.

16.1.3. Environment

Define the Continuous Integration build system, the Issue Tracker system and the Version Control System management in C:\dev\projects\maven-setup\pom.xml:

   <mailingLists />
+
+  <scm>
+    <developerConnection>
+      scm:git:${gitHost}/maven-setup.git
+    </developerConnection>
+    <url>${fisheyeHost}/browse/maven-setup</url>
+    <tag>HEAD</tag>
+  </scm>
+  <ciManagement>
+    <system>Jenkins</system>
+    <url>${jenkinsHost}/job/maven-setup</url>
+  </ciManagement>
+  <issueManagement>
+    <system>JIRA</system>
+    <url>${jiraHost}/projects/MVNSTP</url>
+  </issueManagement>
+  <properties>
+    <devHost>http://freedumbytes.dev.net</devHost>
+    <mavenHost>http://freedumbytes.dev.net/mvn-sites</mavenHost>
+    <tomcatHost>http://freedumbytes.dev.net/tomcat</tomcatHost>
+    <payaraHost>http://freedumbytes.dev.net/payara</payaraHost>
+    <apacheHost>http://freedumbytes.dev.net/manual</apacheHost>
+    <organizationHost>http://freedumbytes.dev.net/mvn-sites/maven-setup/team-list.html</organizationHost>
+    <gitHost>http://freedumbytes.dev.net/git-repo</gitHost>
+    <fisheyeHost>http://freedumbytes.dev.net/fisheye</fisheyeHost>
+    <avatarHost>http://freedumbytes.dev.net/fisheye</avatarHost>
+    <jiraHost>http://freedumbytes.dev.net/jira</jiraHost>
+    <jenkinsHost>http://freedumbytes.dev.net/jenkins</jenkinsHost>
+    <nexusHost>http://freedumbytes.dev.net/nexus</nexusHost>
+  </properties>
 </project>

Tip

Should any of the hosts change and a project could not upgrade to the latest Maven Setup parent it now is possible to override it in the Maven configuration file P:\dev\apps\build\apache-maven-3.3.9\conf\settings.xml:

  <profiles>
     …

+   <profile>
+     <id>hosts</id>
+     <activation>
+       <activeByDefault>true</activeByDefault>
+     </activation>
+     <properties>
+       <gitHost>http://freedumbytes.dev.net/git</gitHost>
+     </properties>
+   </profile>
  </profiles>

It is even possible to override that settings from the command line with the option -DgitHost=http://freedumbytes.dev.net/scm/git.

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

16.1.4.1. Configuration

Setup the initial site descriptor in C:\dev\projects\maven-setup\src\site\site.xml:

+<?xml version="1.0" encoding="UTF-8"?>
+
+<project xmlns="http://maven.apache.org/DECORATION/1.6.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/DECORATION/1.6.0
+                             http://maven.apache.org/xsd/decoration-1.6.0.xsd">
+  <bannerLeft>
+    <name>Free Dumb Bytes</name>
+    <href>${devHost}</href>
+  </bannerLeft>
+
+  <publishDate position="left" format="yyyy-MM-dd HH:mm:ss z" />
+
+  <version position="right" />
+  <body>
+    <menu name="Free Dumb Bytes" inherit="top">
+      <item name="Maven" href="${mavenHost}" />
+      <item name="Git" href="${gitHost}" />
+      <item name="FishEye" href="${fisheyeHost}" />
+      <item name="JIRA" href="${jiraHost}" />
+      <item name="Jenkins" href="${jenkinsHost}" />
+      <item name="Nexus" href="${nexusHost}" />
+      <item name="HTTP Server" href="${apacheHost}" />
+      <item name="Tomcat" href="${tomcatHost}" />
+      <item name="Payara" href="${payaraHost}" />
+      <item name="Development Production Line"
+            href="https://freedumbytes.bitbucket.io/dpl/html/index.html" />
+      <item name="Recent releases" 
+            href="${fisheyeHost}/qsearch?q=%5Bmaven-release-plugin%5D&amp;t=1&amp;s=0" />
+    </menu>
+    <menu inherit="bottom" ref="parent" />
+    <menu inherit="bottom" ref="modules" />
+    <menu inherit="bottom" ref="reports" />
+  </body>
+</project>

Note

Set the landing page for jiraHost as follows:

trick
JIRA Home Page
Figure 16.1. JIRA Home Page

Setup the Project Info Reports in C:\dev\projects\maven-setup\pom.xml:

   </properties>
+
+  <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>summary</report>
+              <report>license</report>
+              <report>project-team</report>
+              <report>modules</report>
+              <report>scm</report>
+              <report>issue-tracking</report>
+              <report>cim</report>
+              <report>distribution-management</report>
+              <report>dependency-info</report>
+              <report>dependencies</report>
+              <report>dependency-management</report>
+              <report>dependency-convergence</report>
+              <report>plugins</report>
+              <report>plugin-management</report>
+              <report>mailing-list</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:///C:/dev/projects/maven-setup/target/site/index.html.

16.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 C:\dev\projects\maven-setup\src\site\site.xml:

   <publishDate position="left" format="yyyy-MM-dd HH:mm:ss z" />
   <version position="right" />
 
+  <skin>
+    <groupId>${skinGroupId}</groupId>
+    <artifactId>${skinArtifactId}</artifactId>
+    <version>${skinVersion}</version>
+  </skin>
+
+  <custom>
+    <fluidoSkin>
+      <topBarEnabled>true</topBarEnabled>
+      <navBarStyle>navbar-inverse</navBarStyle>
+
+      <sideBarEnabled>true</sideBarEnabled>
+      <leftColumnClass>span2</leftColumnClass>
+      <bodyColumnClass>span10</bodyColumnClass>
+
+      <sourceLineNumbersEnabled>true</sourceLineNumbersEnabled>
+      <copyrightClass>pull-right</copyrightClass>
+    </fluidoSkin>
+  </custom>
+
   <body>
     <menu name="Free Dumb Bytes" inherit="top">

Supply the skin settings in C:\dev\projects\maven-setup\pom.xml:

   <properties>
      …
     <nexusHost>http://freedumbytes.dev.net/nexus</nexusHost>
+
+    <skinGroupId>org.apache.maven.skins</skinGroupId>
+    <skinArtifactId>maven-fluido-skin</skinArtifactId>
+    <skinVersion>${mavenFluidoSkinVersion}</skinVersion>
+
+    <mavenFluidoSkinVersion>1.4</mavenFluidoSkinVersion>
   </properties>

   <reporting>

16.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 C:\dev\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
+
+ []
+ Projects that extend from this POM must at least override the following settings:
+
+ * name
+
+ * description
+
+ * url
+
+ * inceptionYear
+
+ * optionally developers and contributors
+
+ * scm
+
+ * ciManagement
+
+ * issueManagement
+
+ []

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.

16.1.5. Plugin Versions

After running mvn site check the Plugin Management, Build Plugins and Report Plugins reports in your browser at file:///C:/dev/projects/maven-setup/target/site/plugin-management.html and file:///C:/dev/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 configured in C:\dev\projects\maven-setup\pom.xml (see also SoftwareEntwicklung Beratung Schulung for latest release notes):

     <mavenFluidoSkinVersion>1.4</mavenFluidoSkinVersion>
+    <mavenCleanPluginVersion>3.0.0</mavenCleanPluginVersion>
+    <mavenToolchainsPluginVersion>1.1</mavenToolchainsPluginVersion>
+    <versionsMavenPluginVersion>2.3</versionsMavenPluginVersion>
+    <mavenPluginPluginVersion>3.4</mavenPluginPluginVersion>
+    <mavenDependencyPluginVersion>2.10</mavenDependencyPluginVersion>
+    <truezipMavenPluginVersion>1.2</truezipMavenPluginVersion>
+    <mavenResourcesPluginVersion>3.0.1</mavenResourcesPluginVersion>
+    <mavenAntrunPluginVersion>1.8</mavenAntrunPluginVersion>
+    <mavenCompilerPluginVersion>3.5.1</mavenCompilerPluginVersion>
+    <mavenAnimalSnifferPluginVersion>1.15</mavenAnimalSnifferPluginVersion>
+    <mavenDependencyCheckVersion>1.4.2</mavenDependencyCheckVersion>
+    <jacocoMavenPluginVersion>0.7.7.201606060606</jacocoMavenPluginVersion>
+    <mavenSurefirePluginVersion>2.19.1</mavenSurefirePluginVersion>
+    <mavenSurefireReportPluginVersion>
+      ${mavenSurefirePluginVersion}
+    </mavenSurefireReportPluginVersion>
+    <mavenFailsafePluginVersion>
+      ${mavenSurefirePluginVersion}
+    </mavenFailsafePluginVersion>
+    <mavenJarPluginVersion>3.0.2</mavenJarPluginVersion>
+    <mavenEjbPluginVersion>2.5.1</mavenEjbPluginVersion>
+    <mavenWarPluginVersion>2.6</mavenWarPluginVersion>
+    <mavenRarPluginVersion>2.4</mavenRarPluginVersion>
+    <mavenEarPluginVersion>2.10.1</mavenEarPluginVersion>
+    <mavenSourcePluginVersion>3.0.1</mavenSourcePluginVersion>
+    <mavenJavadocPluginVersion>2.10.4</mavenJavadocPluginVersion>
+    <mavenAssemblyPluginVersion>2.6</mavenAssemblyPluginVersion>
+    <mavenInstallPluginVersion>2.5.2</mavenInstallPluginVersion>
+    <mavenDeployPluginVersion>2.8.2</mavenDeployPluginVersion>
+    <mavenReleasePluginVersion>2.5.3</mavenReleasePluginVersion>
+    <mavenScmPluginVersion>1.9.5</mavenScmPluginVersion>
+    <mavenSitePluginVersion>3.4</mavenSitePluginVersion>
+    <mavenProjectInfoReportsPluginVersion>2.9</mavenProjectInfoReportsPluginVersion>
  </properties>

Caution

Not upgrading site plugin to 3.5.x yet because of the following 3 issues:

  1. Error parsing site descriptor: TEXT must be immediately followed by END_TAG and not START_TAG (position: START_TAG seen ...

  2. Execution default-site of goal org.apache.maven.plugins:maven-site-plugin:3.5.1:site failed: Illegal character in path at index 1: ${mavenHost}

  3. Reflow Skin does not work with Maven Site Plugin 3.5 due to the fact that the new Maven Site plugin is not loading Velocity tools.

+  <build>
+    <pluginManagement>
+      <plugins>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-clean-plugin</artifactId>
+          <version>${mavenCleanPluginVersion}</version>
+        </plugin>
+        <plugin>
+          <groupId>org.codehaus.mojo</groupId>
+          <artifactId>versions-maven-plugin</artifactId>
+          <version>${versionsMavenPluginVersion}</version>
+          <configuration>
+            <outputEncoding>UTF-8</outputEncoding>
+          </configuration>
+        </plugin>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-plugin-plugin</artifactId>
+          <version>${mavenPluginPluginVersion}</version>
+        </plugin>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-dependency-plugin</artifactId>
+          <version>${mavenDependencyPluginVersion}</version>
+        </plugin>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-resources-plugin</artifactId>
+          <version>${mavenResourcesPluginVersion}</version>
+          <configuration>
+            <encoding>UTF-8</encoding>
+          </configuration>
+        </plugin>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-antrun-plugin</artifactId>
+          <version>${mavenAntrunPluginVersion}</version>
+        </plugin>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-compiler-plugin</artifactId>
+          <version>${mavenCompilerPluginVersion}</version>
+          <configuration>
+            <encoding>UTF-8</encoding>
+          </configuration>
+        </plugin>

Note

Should the compiler plugin 3.x fail with the message Caused by: org.apache.maven.plugin.compiler.CompilationFailureException: Compilation failure and no further information is shown about the real cause, even when using options -e or -X, then try using the older version 2.5.1 as follows: mvn org.apache.maven.plugins:maven-compiler-plugin:2.5.1:compile and hey presto back is the following error message [ERROR] Failure executing javac, but could not parse the error: with the following stack trace for details..

+        <plugin>
+          <groupId>org.jacoco</groupId>
+          <artifactId>jacoco-maven-plugin</artifactId>
+          <version>${jacocoMavenPluginVersion}</version>
+          <configuration>
+            <sourceEncoding>UTF-8</sourceEncoding>
+            <outputEncoding>UTF-8</outputEncoding>
+          </configuration>
+        </plugin>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-surefire-plugin</artifactId>
+          <version>${mavenSurefirePluginVersion}</version>
+        </plugin>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-failsafe-plugin</artifactId>
+          <version>${mavenFailsafePluginVersion}</version>
+          <configuration>
+            <encoding>UTF-8</encoding>
+          </configuration>
+        </plugin>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-jar-plugin</artifactId>
+          <version>${mavenJarPluginVersion}</version>
+        </plugin>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-ejb-plugin</artifactId>
+          <version>${mavenEjbPluginVersion}</version>
+        </plugin>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-war-plugin</artifactId>
+          <version>${mavenWarPluginVersion}</version>
+        </plugin>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-rar-plugin</artifactId>
+          <version>${mavenRarPluginVersion}</version>
+        </plugin>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-ear-plugin</artifactId>
+          <version>${mavenEarPluginVersion}</version>
+          <configuration>
+            <encoding>UTF-8</encoding>
+            <duplicateArtifactsBreakTheBuild>
+              true
+            </duplicateArtifactsBreakTheBuild>
+          </configuration>
+        </plugin>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-source-plugin</artifactId>
+          <version>${mavenSourcePluginVersion}</version>
+        </plugin>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-javadoc-plugin</artifactId>
+          <version>${mavenJavadocPluginVersion}</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>${mavenAssemblyPluginVersion}</version>
+        </plugin>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-install-plugin</artifactId>
+          <version>${mavenInstallPluginVersion}</version>
+          <configuration>
+            <createChecksum>true</createChecksum>
+            <updateReleaseInfo>false</updateReleaseInfo>
+          </configuration>
+        </plugin>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-deploy-plugin</artifactId>
+          <version>${mavenDeployPluginVersion}</version>
+          <configuration>
+            <updateReleaseInfo>true</updateReleaseInfo>
+          </configuration>
+        </plugin>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-release-plugin</artifactId>
+          <version>${mavenReleasePluginVersion}</version>
+          <configuration>
+            <autoVersionSubmodules>true</autoVersionSubmodules>
+          </configuration>
+        </plugin>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-scm-plugin</artifactId>
+          <version>${mavenScmPluginVersion}</version>
+        </plugin>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-site-plugin</artifactId>
+          <version>${mavenSitePluginVersion}</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>${mavenProjectInfoReportsPluginVersion}</version>
         <configuration>
           <dependencyDetailsEnabled>false</dependencyDetailsEnabled>
           <dependencyLocationsEnabled>false</dependencyLocationsEnabled>
           <linkOnly>true</linkOnly>
         </configuration>
         <reportSets>
           <reportSet>
             <reports>
               <report>index</report>

trickAnd produces reports, on demand with -PenableUpdatesReports, of those project dependencies, plugins and properties, which have newer versions available:

   </properties>
+
+  <profiles>
+    <profile>
+      <id>enableUpdatesReports</id>
+
+      <reporting>
+        <plugins>
+          <plugin>
+            <groupId>org.codehaus.mojo</groupId>
+            <artifactId>versions-maven-plugin</artifactId>
+            <version>${versionsMavenPluginVersion}</version>
+            <reportSets>
+              <reportSet>
+                <reports>
+                  <report>dependency-updates-report</report>
+                  <report>plugin-updates-report</report>
+                  <report>property-updates-report</report>
+                </reports>
+              </reportSet>
+            </reportSets>
+          </plugin>
+        </plugins>
+      </reporting>
+    </profile>
+  </profiles>

   <build>

This is for example a property-updates-report:

trick
Maven Versions Property Updates Report
Figure 16.2. Maven Versions Property Updates Report

Tip

VersionEye is a cross-platform search engine for free/libre/open source software libraries, which also shows out of date dependencies of for example javaee-api.

Create a rule set file C:\dev\projects\maven-setup\src\config\maven-versions-rules.xml:

+<?xml version="1.0" encoding="UTF-8"?>
+
+<ruleset comparisonMethod="maven"
+ xmlns="http://mojo.codehaus.org/versions-maven-plugin/rule/2.0.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://mojo.codehaus.org/versions-maven-plugin/rule/2.0.0
+     http://www.mojohaus.org/versions-maven-plugin/xsd/rule-2.0.0.xsd">
+  <rules>
+    <rule groupId="commons-logging" artifactId="commons-logging">
+      <ignoreVersions>
+        <ignoreVersion type="regex">.*-does-not-exist</ignoreVersion>
+      </ignoreVersions>
+    </rule>
+
+    <rule groupId="log4j" artifactId="log4j">
+      <ignoreVersions>
+        <ignoreVersion type="regex">.*-atlassian.*</ignoreVersion>
+      </ignoreVersions>
+    </rule>
+
+    <rule groupId="com.google.guava">
+      <ignoreVersions>
+        <ignoreVersion type="regex">.*-rc.*</ignoreVersion>
+      </ignoreVersions>
+    </rule>
+
+    <rule groupId="log4j" artifactId="log4j">
+      <ignoreVersions>
+        <ignoreVersion type="regex">.*-atlassian.*</ignoreVersion>
+      </ignoreVersions>
+    </rule>
+
+    <rule groupId="com.google.guava">
+      <ignoreVersions>
+        <ignoreVersion type="regex">.*-rc.*</ignoreVersion>
+      </ignoreVersions>
+    </rule>
+
+    <rule groupId="org.springframework">
+      <ignoreVersions>
+        <ignoreVersion type="regex">.*\.M.*</ignoreVersion>
+        <ignoreVersion type="regex">.*\.RC.*</ignoreVersion>
+      </ignoreVersions>
+    </rule>
+
+    <rule groupId="org.hibernate">
+      <ignoreVersions>
+        <ignoreVersion type="regex">.*\.Alpha.*</ignoreVersion>
+        <ignoreVersion type="regex">.*\.Beta.*</ignoreVersion>
+        <ignoreVersion type="regex">.*\.CR.*</ignoreVersion>
+        <ignoreVersion type="regex">.*-atlassian-.*</ignoreVersion>
+      </ignoreVersions>
+    </rule>
+
+    <rule groupId="junit">
+      <ignoreVersions>
+        <ignoreVersion type="regex">.*-beta-.*</ignoreVersion>
+        <ignoreVersion type="regex">.*-brew.*</ignoreVersion>
+      </ignoreVersions>
+    </rule>
+
+    <rule groupId="org.mockito">
+      <ignoreVersions>
+        <ignoreVersion type="regex">.*-dev.*</ignoreVersion>
+        <ignoreVersion type="regex">.*-beta.*</ignoreVersion>
+        <ignoreVersion type="regex">.*-rc.*</ignoreVersion>
+      </ignoreVersions>
+    </rule>
+
+    <rule groupId="org.slf4j">
+      <ignoreVersions>
+        <ignoreVersion type="regex">.*jbossorg.*</ignoreVersion>
+      </ignoreVersions>
+    </rule>
   </rules>
 </ruleset>

To allow free access to this file just upload it as an artifact in the Releases repository of Nexus:

trick
Maven Versions Rules Nexus Upload
Figure 16.3. Maven Versions Rules Nexus Upload

Or just start a new bare Git repository maven-versions-rules by calling /p/dev/apps/windows/batch/git-create-repo.sh /p/dev/data/repo/git maven-versions-rules.git "A ruleSet file containing the rules that control how to compare version numbers." -jenkinsHook in Git Bash (see also repository branches/maven-versions-rules).

Finally configure the rule set usage in C:\dev\projects\maven-setup\pom.xml:

   <properties>
      …
     <skinVersion>${mavenFluidoSkinVersion}</skinVersion>
+    
+    <versionsRulesVersion>1.0-kappa</versionsRulesVersion>
+    <versionsRulesPath>
+      ${nexusHost}/content/groups/public/net/dev/freedumbytes/maven/versions-rules
+    </versionsRulesPath>
 
     <mavenFluidoSkinVersion>1.4</mavenFluidoSkinVersion>
     <pluginManagement>
       <plugins>
         …
 
         <plugin>
           <groupId>org.codehaus.mojo</groupId>
           <artifactId>versions-maven-plugin</artifactId>
           <version>${versionsMavenPluginVersion}</version>
           <configuration>
             <outputEncoding>UTF-8</outputEncoding>
+            <rulesUri>
+              ${versionsRulesPath}/${versionsRulesVersion}/versions-rules-${versionsRulesVersion}.xml
+            </rulesUri>
           </configuration>
         </plugin>

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

    • WorkspaceText file encodingOtherUTF-8

    • Content TypesText set Default encoding to UTF-8 and Update the following:

      • Java Properties File.

      • Java Source File.

      • JSP.

      • JSP Fragment.

      • JSP Tag Definition.

      • XML JSP Tag Definition.

    • EditorsText EditorsSpellingEncodingOtherUTF-8

  • Web apply Encoding ISO 10646/Unicode(UTF-8) for the following:

    • CSS Files.

    • HTML Files.

    • JSP Files.

  • XMLXML FilesEncodingISO 10646/Unicode(UTF-8).

16.1.6. Deployment

Configure the deployment of the project site on the Apache HTTP Server and the artifacts in the Nexus Repository.

16.1.6.1. Site

Enable WebDAV on the Apache HTTP Server (see Section 7.1.13, “Module mod_dav configuration”) for uploading of the Maven sites content and amend the setup C:\dev\projects\maven-setup\pom.xml:

   </issueManagement>
 
+  <distributionManagement>
+    <site>
+      <id>mvn-sitestrick1</id>
+      <name>Maven Documentation Sites</name>
+      <url>dav:${mavenHost}/maven-setup</url>
+    </site>
+  </distributionManagement>
+
   <properties>
     <mavenProjectInfoReportsPluginVersion>2.8.1</mavenProjectInfoReportsPluginVersion>
+
+    <wagonMavenPluginVersion>1.0</wagonMavenPluginVersion>
+    <wagonFtpVersion>2.10</wagonFtpVersion>
+    <wagonWebdavJackrabbitVersion>2.10</wagonWebdavJackrabbitVersion>
   </properties>

   <build>
+    <extensions>
+      <extension>
+        <groupId>org.apache.maven.wagon</groupId>
+        <artifactId>wagon-ftp</artifactId>
+        <version>${wagonFtpVersion}</version>
+      </extension>
+      <extension>
+        <groupId>org.apache.maven.wagon</groupId>
+         <artifactId>wagon-webdav-jackrabbit</artifactId>
+         <version>${wagonWebdavJackrabbitVersion}</version>
+      </extension>
+    </extensions>
+    
     <pluginManagement>
           <artifactId>maven-site-plugin</artifactId>
           <version>${mavenSitePluginVersion}</version>
           <configuration>
+            <generateSitemap>true</generateSitemap>
             <inputEncoding>UTF-8</inputEncoding>
             <outputEncoding>UTF-8</outputEncoding>
           </configuration>

and make note of this in C:\dev\projects\maven-setup\src\site\apt\index.apt:

  Projects that extend from this POM must at least override the following settings:

  * name

  * description

  * url

  * inceptionYear

  * optionally developers and contributors

  * scm

  * ciManagement

  * issueManagement
+
+ * 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.3.9\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://freedumbytes.dev.net/mvn-sites/maven-setup/index.html.

16.1.6.2. Artifact

Configure Nexus as the default artifact repository for the artifact deployment with the following <distributionManagement/> settings in the C:\dev\projects\maven-setup\pom.xml:

   <distributionManagement>
+    <repository>
+      <id>nexus-releases</id>
+      <name>Internal Releases</name>
+      <url>${nexusHost}/content/repositories/releases</url>
+    </repository>
+    <snapshotRepository>
+      <id>nexus-snapshots</id>
+      <name>Internal Snapshots</name>
+      <url>${nexusHost}/content/repositories/snapshots</url>
+    </snapshotRepository>
     <site>
       <id>mvn-sites</id>

Note

Those repositories are defined in the development profile settings.

and amend the C:\dev\projects\maven-setup\src\site\apt\index.apt:

 * Project Information

  This POM defines the following default information:

  * organization

  * developers

  * contributors
+
+ * distributionManagement of the releases and snapshots
+
+ <<Note>>: All supported Maven repositories are configured in 
+ {{{${nexusHost}/index.html#view-repositories}Nexus}}

  []

Note

To filter properties into any supported documentation format, add a .vm extension to the filename. Thus rename the file to C:\dev\projects\maven-setup\src\site\apt\index.apt.vm.

Verify those settings with mvn deploy in your browser at http://freedumbytes.dev.net/nexus/index.html#nexus-search;gav~net.dev.freedumbytes.maven~setup~~~.

trick
Free Dumb Bytes Maven Setup
Figure 16.4. Free Dumb Bytes Maven Setup

16.1.6.3. Navigation tree reuse

To be able to reuse the project setup site descriptor C:\dev\projects\maven-setup\src\site\site.xml attach it as an artifact along with the pom.xml:

     <mavenAssemblyPluginVersion>2.5.3</mavenAssemblyPluginVersion>
+    <buildHelperMavenPluginVersion>1.12</buildHelperMavenPluginVersion>
     <mavenInstallPluginVersion>2.5.2</mavenInstallPluginVersion>
      …
   </properties>

   <build>
     <pluginManagement>
       <plugins>
          …

+        <plugin>
+          <groupId>org.codehaus.mojo</groupId>
+          <artifactId>build-helper-maven-plugin</artifactId>
+          <version>${buildHelperMavenPluginVersion}</version>
+        </plugin>

         <plugin>
           <groupId>org.apache.maven.plugins</groupId>
           <artifactId>maven-install-plugin</artifactId>
       </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>
+            </configurat