Skip to content

Latest commit

 

History

History

web-server

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
app
app
 
 
.gitignore
.gitignore
 
 
Dockerfile
Dockerfile
 
 
README.md
README.md
 
 

README.md

Copyright (C) 2021, Axis Communications AB, Lund, Sweden. All Rights Reserved.

Serve HTTP requests through reverse proxy

This example demonstrates how to setup the Axis device web server (Apache) in a Reverse Proxy configuration, where HTTP requests to the application are routed to a web server CivetWeb running inside the ACAP application and acting as a CGI.

Note

The web server runs on the port specified in the application, however there is a possibility that the port already is in use. For more information on common ports used by Axis devices, see the commonly used network ports in the AXIS OS knowledge base. To change the port of the application, both the web_server_rev_proxy.c and [manifest.json](./app/manifest.json] file have to be updated before building the application.

The advantage of a webserver proxy is that when porting existing code to your ACAP application, its request handling can remain largely unmodified. This eases the task of sharing code between platforms. The webserver proxy method enforces a URL routing scheme as follows:

http://<AXIS_DEVICE_IP>/local/<appName>/<apiPath>

With <appName> and <apiPath> as defined in the manifest.

Note that this example shows the reverse proxy concept using CivetWeb, but you are free to use any webserver of your choice.

Alternative approach

Another example that serves HTTP requests is web-server-using-fastcgi, where the Axis device web server and the supported ACAP API FastCGI are used.

Reverse proxy configuration in Apache server

A reverse proxy configuration provides a flexible way for an ACAP application to expose an external API through the Apache Server in AXIS OS and internally route the requests to a web server running in the ACAP application.

The Apache server is configured using the manifest.json file in an ACAP application. In manifest.json under configuration, it is possible to specify a settingPage and a reverseProxy where the latter will connect the CivetWeb server to the Apache server.

Prior to manifest 1.5.0, reverse proxy was only supported through the postinstall script. The manifest based method is more strict on URLs in order to avoid name clashes that could occur in the old mechanism. When upgrading, your URLs will change to the format shown in Serve HTTP requests through reverse proxy.

The web server running in the ACAP application can also be exposed directly to the network by allowing external access to the port in the network configuration for the device. There are disadvantages with exposing Web Server directly to the network such as non standard ports and no reuse of authentication, TLS and other features that comes with Apache Server.

CivetWeb web server

CivetWeb is an embeddable C web server for Linux. It is a great solution for running a web server on embedded Linux. Apart from being a HTTP server, it has a C API which can be extended as desired. The CivetWeb Web Server documentation describes the configuration in detail. CivetWeb is open source, and will contain different licenses depending on the features you build it with. Please see CivetWeb's repository for more information.

Getting started

These instructions will guide you on how to execute the code. Below is the structure used in the example:

web-server
├── app
│   ├── LICENSE
│   └── manifest.json
├── Dockerfile
└── README.md
  • app/LICENSE - Lists open source licensed source code in the application.
  • app/manifest.json - Defines the application and its configuration.
  • Dockerfile - Builds an Axis container image and the specified example.
  • README.md - Step by step instructions on how to run the example.

Limitations

How to run the code

Below is the step by step instructions on how to execute the program. So basically starting with the generation of the .eap file to running it on a device.

Build the application

Standing in your working directory run the following commands:

Note

Depending on the network your local build machine is connected to, you may need to add proxy settings for Docker. See Proxy in build time.

docker build --platform=linux/amd64 --tag <APP_IMAGE> --build-arg ARCH=<ARCH> .
  • <APP_IMAGE> is the name to tag the image with, e.g., web-server:1.0
  • <ARCH> is the SDK architecture, armv7hf or aarch64.

Copy the result from the container image to a local directory build:

docker cp $(docker create --platform=linux/amd64 <APP_IMAGE>):/opt/app ./build

The build directory contains the build artifacts, where the ACAP application is found with suffix .eap, depending on which SDK architecture that was chosen, one of these files should be found:

  • web_server_rev_proxy_1_0_0_aarch64.eap
  • web_server_rev_proxy_1_0_0_armv7hf.eap

Note

For detailed information on how to build, install, and run ACAP applications, refer to the official ACAP documentation: Build, install, and run.

Install and start the application

Browse to the application page of the Axis device:

http://<AXIS_DEVICE_IP>/index.html#apps

  1. Click on the tab Apps in the device GUI

  2. Enable Allow unsigned apps toggle

  3. Click (+ Add app) button to upload the application file

  4. Select the newly built application package, depending on architecture:

    • web_server_rev_proxy_1_0_0_aarch64.eap
    • web_server_rev_proxy_1_0_0_armv7hf.eap

  5. Click Install

  6. Run the application by enabling the Start switch

The expected output

A user can make a HTTP request to the application API using e.g. cURL

curl -u <USER>:<PASSWORD> --anyauth http://<AXIS_DEVICE_IP>/local/web_server_rev_proxy/my_web_server

Where the expected output is

<html>
 <head><link rel="stylesheet" href="style.css"/></head>
 <title>
  ACAP Web Server Example
 </title>
 <body>
  <h1>ACAP Web Server Example</h1>
  Welcome to the web server example, this server is based on the
        <a href="https://github.com/civetweb/civetweb">CivetWeb</a> C library.
 </body>
</html>

To view the rendered web page, click on the Open button of the application from the Apps tab of the device GUI. Alternatively, browse directly to http://<AXIS_DEVICE_IP>/local/web_server_rev_proxy/my_web_server.

The application log can be found by either

  • Browse to http://<AXIS_DEVICE_IP>/axis-cgi/admin/systemlog.cgi?appname=web_server_rev_proxy.
  • Browse to the application page and click the App log.

License

Apache License 2.0