Panorama > Panorama Server > Server Setup
 
Using an External Web Server

The Panorama X Team Server uses http protocol to communicate between computers, and for that purpose it includes a built-in http (web) server. This server is completely self-contained within Panorama, and it is used to facilitate communication between the server and Panorama clients (for database sharing), and also between the server and web client software (Safari, Chrome, Firefox, etc.).

For most applications, Panorama’s built-in http server is all that is required. However, this internal server does have a few limitations that may require a more fuller featured http server to be used as a front end for Panorama’s server (more on what we mean as a “front end” in a moment).

If any of the above issues apply to you, you’ll need to set up an external web server for use with Panorama, as described below. Or, if you already have external web server software in use, you will probably want to set it up as a front end for Panorama simply for continuity with your existing web site.

How an External Server Works with Panorama Server

In normal operation, client applications communicate directly with Panorama’s internal http server, usually over port 8080 as shown in this diagram.

When an external http server is used, client applications communicate with the external server, which then relays the data to Panorama’s internal server (Panorama’s internal server must always be running, in either case). Responses from Panorama go back through the external http server, and then back to the original client application. (Note: The external server software and Panorama X Server run on the same computer.)

It’s also possible for some clients to communicate directly with the internal server, while others communicate using the external server as a relay.

The Apache HTTP Server

At this point you may be wondering where to get an external http server. The good news is you already have one! Every Macintosh computer comes preloaded with an industrial class http server called Apache. All you have to do is turn it on. (To learn more about Apache, see The Apache Server Project.)

Starting and Stopping the Apache HTTP Server

To control the Apache server built into macOS, open the Apache panel of the Preferences dialog (in the File menu). (If you haven’t already done so, you’ll need to unlock the Lock Panorama X Server padlock in the Advanced panel to make the Apache panel visible, see installing and Launching Panorama Server).

The first step in using this panel is to enter the password for your macOS user account. This is the same password you use to log onto the computer, not the password for your Panorama account. (Note: Your user account must have administrator privileges to run the Apache server.)

Press the Start Apache button to start the http server. If this is the first time you have started Apache, you may see a dialog sheet listing the changes Panorama is about to make to your computer’s http.conf configuration file. These changes are necessary to allow Apache to relay communications to Panorama Server.

If you want to learn more about these changes and why they are necessary, see the the http.conf section below. Otherwise, just press the Accept Changes and Start Apache button. After a short delay the status indicator will show that Apache is running on this computer.

To verify that Apache is running, you can click on the gear icon and choose Open Apache index.html in Safari from the popup menu.

This will open a Safari browser window and display the Apache home page. Unless you’ve edited the index.html file, the home page will look like this:

This test page verifies that Apache is running on its own. To also verify that the Apache/Panorama Server relay is working, click the gear icon and choose Open Panorama X Server Status from the popup menu.

If everything is working properly, this Safari browser window will open and display a status page that is similar to this.

Remember, both Apache and Panorama X Server must be running for this test to work. If Apache is running but Panorama X Server is not, the browser window will look like this:

If you see an error message like this, make sure that Panorama X Server is running, using the steps described in Installing and Launching Panorama Server.

Under the Hood

When you press the Start Apache button, Panorama not only starts Apache but it also makes sure it is configured properly. The following sections describe the technical details of how this configuration process works. This information will be useful for advanced technical users if you need to customize the configuration for special needs, and may be useful for debugging if you run into problems.

Panoramax.cgi

The stock version of Apache supplied by Apple doesn’t know how to communicate with Panorama Server. To enable this, Panorama adds a special program called a CGI to Apache. CGI stands for Common Gateway Interface, a standard for dynamic generation of web pages by a web server. Panorama includes a custom CGI that links Apache with the Panorama X internal server. This Objective-C program is called Panoramax.cgi. When the Start Apache button is pressed this program is automatically placed in the correct folder for Apache to use it (normally /Library/WebServer/CGI-Executables) with the correct permissions. If this program is ever accidentally damaged or removed, simply stop and restart Apache and Panorama will automatically re-install it.

If for some reason you don’t want Panoramax.cgi to be installed when starting Apache, uncheck this in the Advanced Options section of the panel. However, unchecking this option will almost certainly prevent Apache from working with Panorama Server.

There’s no reason for you to need to ever look at the Panoramax.cgi file, but if you want to, you can click on the gear icon and choose Reveal CGI-Executables folder in Finder. (The computer shown in this screen shot also has Panorama.cgi installed in this folder. This was the CGI for Panorama 6 Server.)

http.conf

Apache is a very complex program with many many many options. These options are controlled by a special configuration file named httpd.conf, usually located at /private/etc/apache2/httpd.conf. The default httpd.conf file supplied by Apple does not enable CGI programs, so it must be modified so that it can use Panoramax.cgi to communicate with Panorama Server. The first time you start Apache on a computer, Panorama will determine the patches necessary for the httpd.conf file. Before actually making the patch changes permanent, Panorama will display the exact changes it is about to make. Lines that will be removed are shown in red, lines that will be added are shown in green.

Note: If you trust Panorama to make any necessary patches and don’t want it to bother you with display of the necessary changes, uncheck the Display and confirm httpd.conf configuration changes option. If this option is unchecked Panorama will just go ahead and make the changes without asking you.

if you want to make the changes yourself manually, you can do that instead. To reveal the location of the httpd.conf file, click on the gear icon and choose Reveal httpd.conf in Finder from the popup menu.

You can’t edit the httpd.conf file with a regular text editor because it has special permissions. We’ve had good luck using the commercial program BBEdit, available in the Mac App Store. BBEdit has special code designed for working with protected files like httpd.conf. If you have BBEdit on your system, you can open the httpd.conf file in it directly from the gear menu.

The httpd.conf file contains hundreds of lines. To allow Apache to work with Panorama Server, you must make two changes. First, find the line that loads the CGI module. It will look like this:

#LoadModule cgi_module libexec/apache2/mod_cgi.so

The first character of this line is a # symbol, which means that the line is “commented out” (disabled). We need the CGI module to load, so the # symbol must be removed, like this.

LoadModule cgi_module libexec/apache2/mod_cgi.so

In addition to loading the CGI module, the CGI module must be enabled. Look for a code block like this.

#
# "/Library/WebServer/CGI-Executables" should be changed to whatever your ScriptAliased
# CGI directory exists, if you have that configured.
#
<Directory "/Library/WebServer/CGI-Executables">
	AllowOverride None
	Options None
	Require all granted
</Directory>

Change this block to look like below. (The AddHandler line is new, and the Options line is changed from None to +ExecCGI).

#
# "/Library/WebServer/CGI-Executables" should be changed to whatever your ScriptAliased
# CGI directory exists, if you have that configured.
#
<Directory "/Library/WebServer/CGI-Executables">
	AllowOverride None
    AddHandler cgi-script .cgi .pl .tcl .py
	Options  +ExecCGI
	Require all granted
</Directory>

When you press the Start Apache button, Panorama will notice that these patches have already been made, and won’t try to make them again. However, if you don’t want to Panorama to even check whether the patch is necessary, uncheck the Automatically configure httpd.conf for Panoramax.cgi option.

Any changes to the httpd.conf file only go into effect the next time Apache starts up. If you edit the file while Apache is running, you’ll need to stop and restart Apache. You can do that either with the button at the top of the panel, or manually as described in the next section.

Manually Starting and Stopping Apache

In addition to using the big button at the top of the Apache panel, you can also manually start and stop Apache using the command line. Start by opening Terminal.app, which is found in the /Applications/Utilities/ folder.

With a terminal window open, type in this command to start Apache:

sudo -s launchctl unload -w /System/Library/LaunchDaemons/org.apache.httpd.plist

Terminal.app will ask you to type in your password.

After you type in your password, Apache will start. There’s no indication in the terminal window except that another prompt appears.

If you look in the Preferences>Apache panel, however, you’ll see that Apache is running, just as if you had pressed the Start Apache Web Server button. (In fact, this button runs this terminal script on your behalf.)

To stop Apache manually, follow the same steps except for using this slightly different script.

sudo -s launchctl unload -w /System/Library/LaunchDaemons/org.apache.httpd.plist

Note: If the system shuts down or reboots with Apache running, Apache will automatically restart the next time the system starts up. There is no special relaunch procedure necessary for Apache.

Using TCP/IP vs. AppleEvent Protocol

As described earlier, communication between Apache and Panorama X Server is normally done via TCP/IP. However, you can also choose to use AppleEvents.

If you are using macOS 10.14 or later, AppleEvents may not work because of security restrictions in the OS. If you are using an older version of macOS then AppleEvents is available as an option, but we usually recommend sticking with TCP/IP.

Using Other External Server Software

Apache is convenient because it comes pre-installed on macOS, but you can use any web server that support the CGI (Common Gateway Interface) standard (nginx, lighttpd, etc.). However if you use something other than Apache you’ll have to do the configuration yourself, including installing the Panoramax.cgi program and editing any configuration files as necessary, and you’ll want to keep in mind that ProVUE does not test Panorama X server with alternative web server software, and cannot provide technical support.

To install the Panoramax.cgi program in a custom location, click on the gear icon and choose Manually Install PanoramaX.cgi… from the popup menu.

Panorama will display a dialog allowing you to choose the name and location where the program will be installed.

Consult the documentation for your web server software to find out where CGI programs should be installed.

See Also

History

VersionStatusNotes
10.2NewNew in this version.