An Easy Way to Embed Reporting in Linux Apps Using Docker

Telerik Reporting has recently removed all dependency on Windows-only libraries, allowing you to host your production applications in lightweight and cost-effective Linux environments. With Docker, this process is even easier to achieve.

Why Linux?

There are many great reasons why you may wish to deploy your production Progress Telerik Reporting application on Linux. Linux runs very fast, and the operating system can be customized to meet the application’s needs. Linux is easy to upgrade, easy to maintain and uses fewer resources to operate than a Windows OS. Additionally, Linux-based cloud hosting is often much more cost-effective than the Windows-based equivalent for the same processing power.

Most .NET developers prefer to work with familiar tools in Windows, such as Visual Studio. Building applications in Linux used to require learning clunky editor such as vi and mastering the subtleties of the Bash shell. Today, with the advent of the Windows Subsystem for Linux (WSL2) and innovative tools like Visual Studio Code, you can bridge the gap between Windows and Linux.

Using Visual Studio code, you can keep most of the performance enhancers you’re accustomed to, work in a Windows operating system and also gain access to a powerful remote terminal connecting you to your locally running instance of Linux in WSL2. This is truly the best of both worlds!

Direct Hosting vs. Docker

With Nginx

You can always choose to forgo Docker and host your application directly in a Linux installation such as RedHat or Ubuntu. Generally, this requires more configuration but can be useful if you want to use other tools and services in the same instance. Native tools like Nginx allow you to host directly in Linux. Like any operating system, you will need to handle upgrades, manage version changes and resolve conflicts. This is an extremely powerful alternative, with a steep learning curve.

With Docker

Using Docker, you can obfuscate away all the minutia of setting up the operating system. Your applications are built on one of a series of pre-configured base images. These images are available in a variety of flavors. Some are built for debugging and have added tools for those tasks. Some are optimized for production and contain only the minimum necessary packages for that task. Some even come pre-configured for use with load-balancers. This allows you to choose, change and experiment with hosting on different base images by changing just a single line of code in your Dockerfile (more on that later).

You also gain portability with Docker, allowing you to move your applications from server to server, on-premises to the cloud with only a few clicks of the mouse. Integrations with Git and CI/CD pipelines further empower you to focus on the application itself instead of the details of hosting.

Follow along with me below to build and launch a Telerik Reporting–empowered ASP.NET web application.

Getting Started

Prerequisites

• .NET SDK 8.0
• Visual Studio Code
• Docker Desktop for Windows
• Windows PowerShell

Building Your Application

Follow the instructions below to create a new web application and test it.

• Create a new folder for your application in a convenient place named LinuxDockerBlog.
• Open Windows PowerShell and navigate to that folder.
• Run the below commands to create a new web application and open it in Visual Studio Code.

dotnet new webapp -o LinuxDockerBlog  
code -r LinuxDockerBlog  

• Your application should now be opened in Visual Studio Code. Select Run > Run Without Debugging or press Ctrl+F5 to launch the web app. (If asked to select a debugger, choose C#/Default Configuration.)

The sample web app will launch, and you’ll see the below in a new window:

Adding Telerik Reporting REST Service

Next, we will need to add the Telerik Reporting libraries and supporting code to the application. This will set up the Telerik Reporting REST Service, which is the Cadillac engine of the Telerik Reporting architecture.

First, you’ll need to configure access to the Telerik Private NuGet Feed to access the libraries. To do this, you will want to check if you have the Telerik NuGet server in your package sources list:

• Open a Terminal Window from Terminal > New Terminal
• Run the following command:

dotnet nuget list source  

• If you do not see nuget.telerik.com—it is a quick fix. Run the following command (after replacing the placeholders with your credentials):

dotnet nuget add source "Telerik" 
  --source "[https://nuget.telerik.com/v3/index.json](https://nuget.telerik.com/v3/index.json)" --username 'api-key' 
  --password '<PASTE YOUR TELERIK KEY HERE>' --store-password-in-clear-text  

• Add the following three libraries with this command:

dotnet add package 
<PACKAGE_NAME>  

1. Telerik.Reporting.Services.AspNetCore (or Telerik.Reporting.Services.AspNetCore.Trial)
2. Telerik.Reporting.OpenXmlRendering (or Telerik.Reporting.OpenXmlRendering.Trial)
3. Telerik.Drawing.Skia

• Add NewtonsoftJson to the Builder object in Program.cs:

builder.Services.AddRazorPages().AddNewtonsoftJson();

• Add the below configuration object to the builder.

builder.Services.TryAddSingleton<IReportServiceConfiguration>(sp =>
    new ReportServiceConfiguration
    {
        // The default ReportingEngineConfiguration will be initialized from appsettings.json or appsettings.{EnvironmentName}.json:
        ReportingEngineConfiguration = sp.GetService<IConfiguration>(),
        // In case the ReportingEngineConfiguration needs to be loaded from a specific configuration file, use the approach below:
        //ReportingEngineConfiguration = ResolveSpecificReportingConfiguration(sp.GetService<IWebHostEnvironment>()),
        HostAppId = "ReportingNet6",
        Storage = new FileStorage(),
        ReportSourceResolver = new UriReportSourceResolver(System.IO.Path.Combine(sp.GetService<IWebHostEnvironment>().ContentRootPath, "Reports"))
    });

• Configure the endpoints by adding the below code. Be sure to add it after the UseRouting() call.

app.UseEndpoints(endpoints =>
{
endpoints.MapControllers();
});

• Next add a Controllers folder to your project.
• Create a new file named ReportsController.cs in the Controllers/ folder.
• Replace the content of ReportsController.cs with the below code:

namespace LinuxDockerBlog.Controllers
{
    using System.Net;
    using System.Net.Mail;
    using Microsoft.AspNetCore.Mvc;
    using Telerik.Reporting.Services;
    using Telerik.Reporting.Services.AspNetCore;

    [Route("api/[controller]")]
    [ApiController]
    public class ReportsController : ReportsControllerBase
    {
        public ReportsController(IReportServiceConfiguration reportServiceConfiguration)
        : base(reportServiceConfiguration)
        {
        }

        protected override HttpStatusCode SendMailMessage(MailMessage mailMessage)
        {
            throw new System.NotImplementedException("This method should be implemented in order to send mail messages");
        }
    }
}

• Test your application by launching with Ctrl+F5.
• Navigate to _http://localhost:<port>/api/reports/formats_.

If everything is working as expected, you should see some JSON output of the available rendering formats.

Writing a Dockerfile

A Dockerfile is the recipe that tells Docker how to build your web application into an image. It’s a text file containing instructions on how to build the image. For full information on how to write a custom Dockerfile, refer to the Writing a Dockerfile docs.

• Create a file called Dockerfile in the root of your project.
• Copy the below instructions into the Dockerfile:

FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base

WORKDIR /app
EXPOSE 8080

RUN apt-get update
RUN apt-get install -y libfreetype6
RUN apt-get install -y libfontconfig1

#Stage 1
FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base

WORKDIR /app
EXPOSE 8080

RUN apt-get update
RUN apt-get install -y libfreetype6
RUN apt-get install -y libfontconfig1

#Stage 2
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
ARG BUILD_CONFIGURATION=Release
WORKDIR /src

COPY . ./LinuxDockerBlog/

ARG TelerikNugetServerApiKey
ENV TelerikNugetServer_API_KEY $TelerikNugetServerApiKey

RUN dotnet restore ./LinuxDockerBlog/LinuxDockerBlog.csproj

WORKDIR /src/LinuxDockerBlog
RUN dotnet publish LinuxDockerBlog.csproj -c release -o /app --no-restore

# Stage 3
FROM mcr.microsoft.com/dotnet/aspnet:8.0
EXPOSE 8080
WORKDIR /app
COPY --from=build /app .
USER $APP_UID
ENTRYPOINT ["./LinuxDockerBlog"]

This is a multi-stage build. Notice that in Stage 1 we add some extra libraries that Telerik Reporting will need to function in Linux that are not part of the standard base image.

In the second stage, we copy the web application file from the local folder to a folder in the image called LinuxDockerBlog with the COPY instruction.

We also set an environment variable using ENV, this value is passed from the command line as a docker build argument ARG. This environment variable can be used to pass information such as an API key for NuGet.

In the final stage, the output from the _RUN dotnet publish_ command is copied into the /app/ folder in the image. The EXPOSE instruction tells the image to make the application available via port 8080 of a running container. The ENTRYPOINT instruction indicates the location of the default executable.

Building an Image

In Windows PowerShell, navigate to the project folder containing the Dockerfile and build the image using the following command.

Notice the “.” at the end? This is telling the command to use the current directory to look for a Dockerfile there.

docker build -t linuxdockerblog .
-or-
docker build -t linuxdockerblog --build-arg TelerikNugetServerApiKey=<YOUR_API_KEY> .

You will need to create a nuget.config file to authenticate with the Telerik Private NuGet Feed. See the docs for help creating this config file.

You can now verify that the image was created by using the following command:

docker images  

You should see something similar to this:

Create a Container

Now that an image has been created, you can run it in a container. In your Windows PowerShell, run the following command:

docker run -it --rm -p 5123:8080 --name linux_reporting linuxdockerblog  

• The _-it_ options allow for an interactive if you need to type a password.
• The _--rm_ option will remove the created container when you kill the process. (This is great for debugging and testing. If you don’t want the container to shut down when you close the terminal, use _-d_ instead.)
• The _-p_ option maps a host (your computer) port to the container’s exposed port: -p HOST_PORT:CONTAINER_PORT. Since we know we exposed port 8080, we can pick any available host port and map it to 8080. This is the port you’ll use to access the application.

You can now test your container by accessing the port on localhost, e.g., http://localhost:5123/.

You can open Docker Desktop to see the container and images you created.

Conclusion

Telerik Reporting is an excellent candidate for use in Linux hosting due to recent refactoring to use the SkiaSharp libraries. Combined with the power of Docker, you can easily build web applications with embedded reporting for Linux and run it in a lightweight container.

This same image can be run anywhere docker is provided, taking all the guesswork out of hosting. This straightforward approach provides you with a simple, portable and reusable solution to hosting your applications in Linux both locally and in the cloud.

New to Telerik Reporting? Try it free for 30 days!

Try Now