Heroku

Note: This application repository is no longer officially maintained as of January 2023. While the deployment instructions below remain valid, users should be aware that the codebase and dependencies may require updates for production use.

This document provides a comprehensive guide for deploying, configuring, and maintaining the application on the Heroku cloud platform. It is intended for developers responsible for the application's deployment and operational management.

A hosted demo version of this application is available at https://the-example-app-csharp.herokuapp.com/.

Heroku Overview

Heroku is a Platform as a Service (PaaS) that enables developers to build, run, and operate applications entirely in the cloud. It abstracts away infrastructure management, allowing the team to focus on code. The platform manages servers, deployment, load balancing, and scaling.

This application is designed for seamless deployment to Heroku, as evidenced by the inclusion of an app.json manifest and a "Deploy to Heroku" button in the README.md. The application supports two deployment strategies:

1. Buildpack Deployment: The default strategy utilizes Heroku's buildpack system to compile and run the ASP.NET Core 2.1 application.
2. Docker Deployment: The application includes a Dockerfile for container-based deployment using Heroku's Container Registry.

Both strategies run the application within managed containers called "dynos".

Note: This application also supports deployment to Azure. For Azure deployment instructions, refer to the Azure deployment documentation.

For more general information on deployment strategies, see the CI/CD documentation.

app.json

The app.json file is a manifest that describes the application and its dependencies, making it easy to deploy and configure on Heroku. It is the foundation for the "One-click deploy" feature.

{
  "name": "The example app .NET",
  "description": "This is \"The Example App\", a reference for building your own applications using Contentful.",
  "repository": "https://github.com/contentful/the-example-app.csharp",
  "keywords": [ "aspnet", "core", "contentful", "example" ],
  "stack": "heroku-16",
  "website": "https://www.contentful.com/",
  "logo": "https://the-example-app-nodejs.herokuapp.com/images/logo-node.svg",
  "success_url": "/",
  "buildpacks": [
    {
      "url": "https://github.com/jincod/dotnetcore-buildpack"
    }
  ]
}

Key Configuration Details

• name & description: Provide metadata for the Heroku application dashboard.
• repository: Specifies the source code location, which Heroku clones during deployment.
• stack: Defines the base operating system image for the dyno. This project is configured for heroku-16 (Ubuntu 16.04).

  Note: heroku-16 is deprecated. For long-term maintenance, it is highly recommended to update the stack to a supported version (e.g., heroku-22) and test compatibility.

• success_url: The relative path to redirect the user to after a successful deployment via the "Deploy to Heroku" button.
• buildpacks: An array specifying the buildpacks to use. This is a critical field that instructs Heroku how to compile the .NET Core application. The application uses the jincod/dotnetcore-buildpack to build and run ASP.NET Core applications on Heroku.

Deployment Methods

Buildpack Deployment (One-click Deploy)

The project repository includes a "Deploy to Heroku" button, which provides a streamlined, automated setup process. When clicked, Heroku uses the app.json manifest to configure the application automatically.

This method uses the jincod/dotnetcore-buildpack (as specified in app.json) to build and run the ASP.NET Core application.

Docker Deployment

The application includes a Dockerfile that enables deployment via Heroku's Container Registry. This multi-stage Docker build:

1. Build Stage: Uses microsoft/dotnet:2.1-sdk to restore dependencies and publish a Release build
2. Runtime Stage: Uses microsoft/aspnetcore:2.1 as the base image and copies the compiled application

Environment Configuration

The Dockerfile sets ASPNETCORE_ENVIRONMENT=Heroku, which allows the application to load Heroku-specific configuration from an appsettings.Heroku.json file (following the ASP.NET Core environment-specific configuration pattern).

The application requires the following Contentful configuration:

• ContentfulOptions:DeliveryApiKey: Your Contentful Delivery API key
• ContentfulOptions:PreviewApiKey: Your Contentful Preview API key
• ContentfulOptions:SpaceId: Your Contentful Space ID
• ContentfulOptions:UsePreviewApi: Boolean flag to toggle between Delivery and Preview API (typically false for production)

These can be configured either through an appsettings.Heroku.json file or via Heroku environment variables using the ASP.NET Core configuration naming convention (e.g., ContentfulOptions__DeliveryApiKey).

Security Configuration

The application automatically enforces HTTPS in non-development environments (see Startup.cs:97-105). When deployed to Heroku, the application checks the X-Forwarded-Proto header and redirects HTTP requests to HTTPS with a 301 status code. Heroku's router sets this header automatically, so no additional configuration is required.

Deployment Steps

To deploy using Docker:

# Login to Heroku Container Registry
heroku container:login

# Build and push the Docker image
heroku container:push web -a your-app-name

# Release the image to your app
heroku container:release web -a your-app-name