How to Install Apache Tomcat on Mac OS Sierra

Our previous tutorial on installing Tomcat on El Capitan had a lot of interest, so here it is an updated (but broadly similar) tutorial for MacOS Sierra.

In this tutorial, we will be using the open-source package manager Homebrew. If you’re not already using homebrew, check out its popularity on GitHub. It’s highly recommended for use with developing on Macs as it makes keeping track of installed software 100 times cleaner than doing it manually (everything is stored in one place, packages are easy to remove, upgrade and find configs for).If you don’t already have Homebrew, install it with:

First, open your Mac terminal window. If you don’t already have Homebrew, install it with:

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"


Step 1: Install Tomcat

Now we can easily install and track the version of Tomcat we’re using and config files etc with the following command:

brew install tomcat

This will take care of the downloading, installation and configuration of Tomcat and manage its dependencies as well. Take note of the output, brew commands are typically really good at displaying concise but useful info, errors and other help.

Homebrew keeps all installed packages (called “kegs”) in a “Cellar” folder – they like their beer references. By default, this is located in the /usr/local/ directory, so there should now be a tomcat folder listed by the command:

ls /usr/local/Cellar

Although an easier shortcut is available as:

brew list

To get more info on Tomcat specifically:

brew list tomcat

This should output something similar to:

$ brew list tomcat
/usr/local/Cellar/tomcat/8.5.15/bin/catalina
/usr/local/Cellar/tomcat/8.5.15/libexec/bin/ (15 files)
/usr/local/Cellar/tomcat/8.5.15/libexec/conf/ (10 files)
/usr/local/Cellar/tomcat/8.5.15/libexec/lib/ (25 files)
/usr/local/Cellar/tomcat/8.5.15/libexec/temp/safeToDelete.tmp
/usr/local/Cellar/tomcat/8.5.15/libexec/webapps/ (573 files)
/usr/local/Cellar/tomcat/8.5.15/RELEASE-NOTES
/usr/local/Cellar/tomcat/8.5.15/RUNNING.txt

The listed binary file Catalina is the “servlet container” used to run the Apache Tomcat server. This can now be started using the command:

catalina run &

The ampersand at the end makes the process run in the background, so after pressing the return key you get your terminal back but Catalina is still running in the background, you can remove it if you want to keep a dedicated window on the process.

Catalina can be stopped using:

catalina stop

 

Step 2: Configure Tomcat

Apache Tomcat comes with an inbuilt GUI management suite, however, for security reasons, this is disabled by default (to avoid dangerous default usernames/passwords). To enable the GUI manager, first edit the file:

nano /usr/local/Cellar/tomcat/8.5.15/libexec/conf/tomcat-users.xml
  • Nano is a text editor that comes with MacOS, although any will do.
  • If the file is blank or not found, you probably have a slightly different version of Tomcat installed, hit ctrl + x to exit, then run the command brew list tomcat and replace the above version number with the one you have installed.

Scroll to the bottom of the file and you should see several user entries surrounded such as:

<!–
<role rolename=”tomcat”/>
<role rolename=”role1″/>
<user username=”tomcat” password=”<must-be-changed>” roles=”tomcat”/>
<user username=”both” password=”<must-be-changed>” roles=”tomcat,role1″/>
<user username=”role1″ password=”<must-be-changed>” roles=”role1″/>
–>
</tomcat-users>

The <!– …  –> means these users are commented out. Leave them as they are and add a new entry after but above the </tomcat-users> line with the “manager-gui” role:

<user username=”someUser” password=”somePassword” roles=”manager-gui”/>

So the file now looks like:

<!–
<role rolename=”tomcat”/>
<role rolename=”role1″/>
<user username=”tomcat” password=”<must-be-changed>” roles=”tomcat”/>
<user username=”both” password=”<must-be-changed>” roles=”tomcat,role1″/>
<user username=”role1″ password=”<must-be-changed>” roles=”role1″/>
–>
<user username=”someUser” password=”somePassword” roles=”manager-gui”/>
</tomcat-users>

Obviously, you should use a unique username & password for security!

Now, start Catalina again:

catalina run
  • If you get errors, you probably need to stop it first, use catalina stop
  • By default, Tomcat runs on port 8080. There’s a really useful command to see what services are running on this a port: lsof -i :8080 (you may need to prefix with sudo for admin protected ports like 80).

Now if you go to the following page you should see a management GUI:

http://localhost:8080/manager/html

Here you can deploy .war files or exploded directories using the Deploy console and existing servlets are listed. You can even try visiting the already deployed servlets by appending the listed path to localhost:8080 (the default tomcat port):

So, the following should give the docs & some examples:

http://localhost:8080/docs
http://localhost:8080/examples

Enter the .war file location you wish to deploy and the desired path into the Deploy section and your application should now be listed as running with its path. Additionally, this can be used with an IDE like Netbeans or IntelliJ to run & debug servers using their configuration windows.

Any questions, please ask in the comments, and please share this article if you found it helpful.

Advertisements

Setup PHP Dev Environment on Mac OS X Sierra – Apache, MySQL & PHPMyAdmin

Getting the development environment right at the start is vitally important to productive application development. Here we will setup a flexible “LAMP” development environment on the latest Mac Os X, El Capitan. We will focus on keeping the development platform flexible and stable, centrally managing all system & application dependencies. Within a few minutes, we will hopefully have advanced PHP web applications serving up pages, but with the ability to integrate extra system components specific to your application.

System (optional)

Apple’s native development IDE is XCode, it’s not great for PHP but provides handy tools and installing it kind of tells Apple your computer’s being used for software development and to unlock related features. If you’re starting on a completely fresh system, it’s a good idea to install Apple’s Xcode tools. Open up the Terminal App, e.g. cmd + space then: terminal  and type:

sudo xcode-select --install
sudo xcodebuild -license

You will have to agree to some terms & conditions but prevents later problems using common tools like Git.

Install Apache and PHP7 (or other versions)

Install the amazing and free open-source Homebrew  package management system which will make open-source software development far more manageable. If you’re not yet convinced by Homebrew, check out its popularity on GitHub. Install Homebrew as such:

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

As of writing, the most recent version of PHP is 7.0, although Mac already has PHP and Apache inbuilt, we will install it using Homebrew to better manage all development services & dependencies – they’ll be all in one place, managed using a standard set of commands. Allowing us to easily upgrade & downgrade PHP, also since Apache (the web server / engine) keeps changing between MacOS releases, we will use Homebrew to manage and keep it consistent.

Fist stop the default Apache service, in the terminal type:

 sudo apachectl stop
 sudo launchctl unload -w /System/Library/LaunchDaemons/org.apache.httpd.plist 2>/dev/null
 brew install httpd24 --with-privileged-ports
 brew install php71
[short wait to download files]
 brew services start homebrew/apache/httpd24

This should take a minute or less and Homebrew is usually really good at providing helpful and clean output info, errors and ways to fix them. For example, it may give you info about where the php.ini file is, (e.g. /usr/local/etc/php/7.0/php.ini ) or suggest the following command to automatically start PHP7 at login:

 brew services start homebrew/php/php70

As mentioned, helpful and clean output info is one of Homebrew’s real strong points, always read what it outputs!

Verify PHP7 installation (optional)

These are a few really useful commands to check everything is working, or diagnose any problems:

Format:   command
                     output

    php -v

PHP 7.0.8 (cli) (built: Jun 23 2016 16:32:40) ( NTS )
Copyright (c) 1997-2016 The PHP Group
Zend Engine v3.0.0, Copyright (c) 1998-2016 Zend Technologies

    which php
/usr/local/bin/php

    ls -l /usr/local/bin/php
lrwxr-xr-x  1 maltronic  admin  36 30 Aug 19:20 /usr/local/bin/php -> /usr/local/Cellar/php70/7.0.8/bin/php

     php -i | grep php.ini
Configuration File (php.ini) Path => /usr/local/etc/php/7.0
Loaded Configuration File => /usr/local/etc/php/7.0/php.ini

If for any reason there’s a problem you can manually point php to the desired version. First, check what Kegs are have installed in your Cellar using:

brew list

If no version of php appears, try “tapping” homebrew to enable it to pick up more software kegs then installing php7 like so:

brew tap homebrew/dupes
brew tap homebrew/versions
brew tap homebrew/homebrew-php
brew install php70

You can link to whichever installed PHP version you like, say you wanted to use PHP 5.6 (and have installed it using brew install php56 then create a symbolic link to /usr/local/bin/php:

ln -s /usr/local/Cellar/php56/5.6.23/bin/php /usr/local/bin/php

Enable Debugging (optional)

Stop haphazardly print variables to the screen and become a real pro developer, use debugging! It’s so easy and better for fixing bugs. To install Xdebug and enable IDE debugging using popular IDEs like Netbeans and PHPStorm, install with homebrew:

brew install php70-xdebug

Install MySQL

Although MariaDB is slowly replacing MySQL in open source circles, either can be installed, as such:

brew install mysql

Just replace “mysql” with “mariadb” (for rest of article). The Homebrew MySQL/MariaDB server should now be running, this can be verified with:

brew services list

Typing just brew services lists the Homebrew’s service manager commands. If mysql isn’t already running, type brew services start mysql

Configure Apache

We will keep on using the preinstalled Apache server but edit the Apache config file to enable the PHP7 module. Use Mac’s inbuilt nano editor or another text editor (like Sublime Text):

sudo nano /etc/apache2/httpd.conf

Add the following line:

  LoadModule php7_module /usr/local/opt/php70/libexec/apache2/libphp7.so

Press ctrl + x to quit.

Now, every site we add will be a new VirtualHost in Apache, one of potentially many web applications running on your computer. Whilst you can edit the /etc/hosts file to enable local domain names, a quick and reliable technique is to use different ports to distinguish websites. First, make sure Apache is checking for Virtual Hosts and that there’s no # commenting out the file:

sudo nano /etc/apache2/httpd.conf

Go right to the bottom of the file (ctrl + v is PAGE DOWN) and ensure the following line does not have a # infront, it should look like the middle line below:

...

Include /private/etc/apache2/other/*.conf

...
(i.e. no #, although the * is ok)


Now edit Apache’s VirtualHost config file, using the nano editor command:

sudo nano /etc/apache2/extra/httpd-vhosts.conf

And add a VirtualHost config for your website:

Listen 81

DocumentRoot "/Users/maltronic/my_php_project/web"
ServerName "local.my_php_project"
ErrorLog "/var/log/apache2/my_php_project-error.log"



Options Indexes FollowSymLinks
AllowOverride All
Require all granted

Where the directory (“web” above) is the base directory that will appear on your website (i.e. where index.php or an equivalent would sit).

Now, finally, we restart the Apache server to apply our changes:

sudo apachectl restart

Some errors may appear (especially in regards to domain names), these generally don’t matter although if there’s an obvious problem stated you should fix it and re-run the restart command.

Install PHPMyAdmin

As usual, install PHPMyAdmin using Homebrew:

brew install phpmyadmin

And as usual, Homebrew will give some info on any final steps, which in my case means:

sudo nano /etc/apache2/httpd.conf

Then adding to the bottom of the file (ctrl + v is page down in nano):

Alias /phpmyadmin /usr/local/share/phpmyadmin

Options Indexes FollowSymLinks MultiViews
AllowOverride All

Require all granted


Order allow,deny
Allow from all

Install Composer (optional)

Composer is a near universally adopted PHP package manager that enables your PHP applications to use 3rd party libraries and manage their dependencies (very similar to Homebrew but for your PHP application (on any OS), rather than Mac Operating System).

It’s not needed yet, but most professional and open-source projects use it. For consistency let’s install it using Homebrew:

brew install composer

As usual, look at the screen output for any errors and info.

That’s It

Try loading PHPMyAdmin in a web browser at:

http://localhost/phpmyadmin

By default the MySQL admin user is: root (with no password).

You now have a fully functioning and extremely flexible LAMP development environment. From here you can easily add additional services like Redis, Memcache, RabbitMQ, other databases and whatever else you would like to use in your project


This guide gets updated based on reader comments. Any problems, please comment below or share on social media if you found this guide useful!

Stopping favicon 404 spam in Apache error logs

Favicons display many elements of the dark, early days of the Internet. Typically a 16×16 pixel image in ICO format (wtf is that?), they were introduced back in 1999 with Internet Explorer 5. More recently mobile browsers have followed in this unholy tradition by introducing more favicon files, bringing the list of files needing to be created / handled to:

  • favicon.ico
  • apple-touch-icon-precomposed.png
  • apple-touch-icon.png

Whilst they do provide a nice little visual logo space for your website or company, you may sometimes think they aren’t worth the bother. One unexpected problem: An Apache error log full of 404 errors from web browsers trying to locate /favicon.ico, /apple-touch-icon-precomposed.png and /apple-touch-icon.png files in your website’s root directory.

A simple way to prevent this is to add the following code to your apache virtualhost configuration:

Redirect 404 /favicon.ico

<Location /favicon.ico>
    ErrorDocument 404 "favicon does not exist"
</Location>

Redirect 404 /apple-touch-icon-precomposed.png

<Location /apple-touch-icon-precomposed.png>
    ErrorDocument 404 "apple-touch-icon-precomposed does not exist"
</Location>

Redirect 404 /apple-touch-icon.png

<Location /apple-touch-icon.png>
    ErrorDocument 404 "apple-touch-icon does not exist"
</Location>

Whilst this solution seems the most technically correct, it still means your server is going to be hit with constant 404 requests for the non-existant files on every page and frame load, although thankfully they should no longer be clogging up error logs. A more pragmatic approach is to create 3 blank files, 1 in ICO format and 2 in PNG format, placing them in your website’s root public directory as favicon.ico, apple-touch-icon-precomposed.png and apple-touch-icon.png. A good tip is to set the Expires header to sometime in the distant future to avoid any further favicon requests.

You will also need to add the following code to your page:

<link rel="shortcut icon" href="#" />

Now finally you can live in peace from bombardment of favicon requests …until browser makers start adding new favicon types.