DSF Onboarding and Deployment Guide

Version 1.0

Version	Date	Comments
1.0	30/07/2025	Published Document

This guide outlines the steps the Service Delivery Team needs to follow to get your web application running on DSF’s secure Azure Kubernetes Service (AKS) private cluster, covering both staging and production environments.

This section covers the initial setup and automated deployment to your application’s staging environment. The staging environment is crucial for testing and validation before production release.

What to do: Your first step is to complete the Service Delivery Initiation Form (Version 1.3) that has been provided to you. This document collects essential information about your application and team, which is critical for setting up your dedicated environment.

Why it’s important: The information you provide in this form will be used by the DSF team to:

• Create a dedicated GitHub repository for your application.
• Configure the initial access permissions for your team members to this repository.
• Understand the basic requirements for your application’s deployment.
• Configure the domains that the web application will be hosted on.

Actions:

• Fill out all sections of the Service Initiation Form accurately.
• Send the completed form to the DSF team at dsf-tech@dits.dmrid.gov.cy.

Using the domains provided in the Service Initiation Form, the DSF team provides a Matomo Script and the Matomo IDs (Staging and Production) to the Service Delivery Team. The script should be implemented in the source code (Stage 1: Step 3), and the IDs should be included in the secret files (Stage 1: Step 5, Stage 2: Step 3). For more information, consult the Matomo documentation.

What to do: After submitting your Service Initiation Form, it’s essential to coordinate with the Connecting Digital Services (CDS) Team to configure your application’s integration with core services. These services are vital building blocks for many modern web applications. For more information and technical documentation, consult the CDS documentation available at https://dev.azure.com/cyprus-gov-cds/Documentation.

Why it’s important: The CDS team manages critical shared services that your application might need, including:

• CyLogin (Identity/Authentication Service): If your web application requires user authentication, you’ll need to work with the CDS team to integrate with CyLogin. This ensures secure and consistent user identity management.
• CyConnect (API Gateway): If your application needs to connect to various backend APIs, CyConnect acts as an API Gateway. The CDS team will help you configure access and routing through this gateway.
• CyNotify (Notification Service): For sending automated email or SMS notifications (e.g., for user verification, alerts, or transactional messages), you’ll coordinate with the CDS team to set up access to CyNotify.
• CyPay (Payment Service): CY Pay is used by the Government online services to make payments with credit/debit cards. CY Pay is a broker providing an abstraction between the Government Services and the Payment Service Provider.

Actions: After submitting your Service Initiation Form, contact the CDS team (cds-support@dits.dmrid.gov.cy).

• Communicate your application’s requirements for authentication (CyLogin), backend API connectivity (CyConnect), notification needs (CyNotify), and online payments (CyPay).
• Work collaboratively with the CDS team to ensure all necessary configurations (e.g., API keys, callback URLs, notification endpoints) are completed for these services. This might involve technical discussions and specific configurations within their systems.
• Ensure you obtain any necessary credentials or configuration details provided by the CDS team, as these might be needed in your application’s secrets file (Step 5).

What to do: Once your Service Initiation Form is processed and initial coordination with the CDS team is underway, the DSF team will create a new, private GitHub repository specifically for your application. You will then be granted access to this repository. Your task is to upload your web application’s code to the root of this repository.

Why it’s important: This GitHub repository will be the central source control for your application. All future deployments will be triggered from changes made within this repository.

Actions:

• Accept the invitation to your new GitHub repository.
• Clone the repository to your local development environment.
• Copy your web application’s source code into the root directory of this local repository.
• Commit and push your code to the master (or main) branch of your GitHub repository.

What to do: In the root directory of your GitHub repository, you must create a file named Dockerfile. This file contains instructions for building a Docker image of your web application.

Why it’s important: A Dockerfile defines how your application and all its dependencies are packaged into a self-contained, portable Docker image. This image will be used to run your application within the AKS cluster, ensuring consistent environments and reliable deployments.

Example Dockerfile (adjust for your technology):

# Use an appropriate base image for your application (e.g., Node.js, Python, .NET Core)
# Example for a .NET Core application:
FROM [mcr.microsoft.com/dotnet/sdk:8.0](https://mcr.microsoft.com/dotnet/sdk:8.0) AS build
WORKDIR /app

# Copy the project file and restore dependencies
COPY *.csproj ./
RUN dotnet restore

# Copy the remaining application code
COPY . .
# Build the application
RUN dotnet publish -c Release -o out

FROM [mcr.microsoft.com/dotnet/aspnet:8.0](https://mcr.microsoft.com/dotnet/aspnet:8.0) AS runtime
WORKDIR /app
COPY --from=build /app/out ./

# Expose the port your application listens on
EXPOSE 8080

ENTRYPOINT ["dotnet", "YourApp.dll"]

What to do: Create a file containing all the necessary secrets and configuration settings for your staging environment (e.g., API keys, third-party service credentials, and any credentials or configurations obtained from the CDS team for CyLogin, CyConnect, or CyNotify). The format of this file will depend on your application’s technology (e.g., appsettings.json for .NET, .env for Node.js/Python).

Why it’s important: For security reasons, we strictly avoid storing sensitive information directly within your GitHub repository. By providing this file separately, the DSF team can securely inject these secrets into your application within the AKS cluster as Kubernetes Secrets, ensuring they are not exposed in your codebase.

Actions:

• Create your staging secrets file (e.g., secrets/appsettings.json, .env) with all necessary settings for your staging environment.
• DO NOT commit this file to your GitHub repository.
• Securely provide this file to the DSF team using the agreed-upon secure method (e.g. a secure email).

secrets/appsettings.json example file

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=tcp:yourserver.database.windows.net,1433;Initial Catalog=YourDb;Persist Security Info=False;User ID=youruser;Password=yourpassword;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"
  },
  "ApiKeys": {
    "SomeExternalService": "YourSecureApiKey"
  },
  "CyLoginSettings": {
    "ClientId": "your_cologin_client_id",
    "ClientSecret": "your_cologin_client_secret",
    "AuthorityUrl": "https://auth.cylogin.example.com"
  },
  "CyConnectSettings": {
    "GatewayUrl": "https://api.cyconnect.example.com/your-app-namespace",
    "ApiKey": "your_cyconnect_api_key"
  },
  "CyNotifySettings": {
    "ServiceUrl": "https://notify.cynotify.example.com",
    "AppId": "your_cynotify_app_id",
    "AppSecret": "your_cynotify_app_secret"
  },
  “MatomoId”: “99”,

  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  }
}

.env example file

API_KEY_STRIPE=sk_test_YOUR_STRIPE_KEY 
CYLOGIN_CLIENT_ID=your_cologin_client_id 
CYLOGIN_CLIENT_SECRET=your_cologin_client_secret 
CYLOGIN_AUTHORITY_URL=https://auth.cologin.example.com 
CYCONNECT_GATEWAY_URL=https://api.cyconnect.example.com/your-app-endpoint 
CYCONNECT_API_KEY=your_cyconnect_api_key 
CYNOTIFY_SERVICE_URL=https://notify.cynotify.example.com 
CYNOTIFY_APP_ID=your_cynotify_app_id 
CYNOTIFY_APP_SECRET=your_cynotify_app_secret

What to do: After you have completed the previous steps (code push, Dockerfile creation, and staging secrets file submission), the DSF team will perform the initial deployment of your application to the staging environment on the AKS cluster.

Why it’s important: The DSF team will use the information provided to create the initial Kubernetes deployment files (YAMLs) and securely inject your application’s secrets. This ensures your application is correctly configured and runs securely on the staging cluster for the first time.

Actions:

• Notify the DSF team once you have completed Steps 1-5 at least 3-5 days before the expected deployment day on the staging environment.
• The DSF team will confirm when the initial staging deployment is complete and your application is live on the staging environment.

What to do: Once the initial staging deployment is successful, any future changes you make to your application’s code and push to the master (or main) branch of your GitHub repository will automatically trigger an update and reload of your application on the staging environment of the AKS cluster. The Service Delivery team, in collaboration with the DSF team, will have configured a GitHub Actions workflow for this purpose.

Why it’s important: This automated process (Continuous Deployment) streamlines updates to the staging environment, reduces manual effort, and ensures that your latest code changes are quickly reflected for testing and validation.

Actions:

• Configure a GitHub Actions workflow
• Continue developing your application.
• Whenever you are ready to deploy new changes to staging, simply commit your code and push it to the master (or main) branch of your GitHub repository.
• Monitor your GitHub Actions workflow for deployment status (success or failure) to the staging environment.

Perform UAT and other necessary testing to ensure the functionality, connectivity, and performance of your application are tested and validated.

---

This section outlines the process for deploying your application to the production environment. Production deployments require specific approvals and are manually executed by the DSF team to ensure quality, security, and compliance.

What to do: Before your application can be considered for production deployment, it must undergo and pass a Web Application Security Assessment (WASA) / Penetration Test conducted on the application deployed on the staging environment.

Why it’s important: This critical security assessment identifies potential vulnerabilities in your application, ensuring it meets our security standards and is robust against attacks before handling live user data or operations.

Actions:

• Once your application is stable on the staging environment (after multiple iterations of Stage 1, Step 7), coordinate with the Contracting Authority to schedule and initiate the WASA.
• Address any findings or vulnerabilities identified during the WASA in your code, deploy fixes to staging (via Stage 1, Step 7), and request re-testing until the WASA is successfully passed.
• Obtain official documentation or approval confirming the successful completion and passing of the WASA.

What to do: If your application processes personal data, a Data Protection Impact Assessment (DPIA) report must be completed and officially approved by the Data Protection Commissioner.

Why it’s important: A DPIA helps identify and minimize the data protection risks of a project. Its approval by the Data Protection Commissioner is a legal and compliance requirement, ensuring that personal data is handled responsibly and in accordance with privacy regulations.

Actions:

• Initiate the DPIA process early in your development cycle if your application handles personal data.
• Work with your Legal/Compliance department and the Data Protection Officer to complete the DPIA report.
• Submit the completed DPIA report to the Data Protection Commissioner for review and approval.
• Obtain official documentation of the approved DPIA report.

What to do: Create a separate file containing all the necessary secrets and configuration settings specifically for your production environment. This file should contain production-ready values (e.g., production database connection strings, live API keys, etc.).

Why it’s important: Production environments have different security and operational requirements than staging. Providing a dedicated production secrets file ensures that sensitive production credentials are never mixed with staging ones and are managed with the highest level of security.

Actions:

• Create your production secrets file (e.g., secrets/appsettings.json, .env) with all necessary production-level settings.
• DO NOT commit this file to your GitHub repository.
• Securely provide this file to the DSF team using the agreed-upon secure method, clearly labelling it as the “Production Secrets File.”

What to do: Once your application has successfully passed WASA on staging and all necessary changes have been made and tested, identify the exact Docker image version (SHA digest) that you wish to deploy to production. This is the unique identifier of the built image that was running on your approved staging environment.

Why it’s important: To maintain a controlled and auditable production deployment, we don’t automatically deploy the latest code. You must explicitly tell us which exact, tested, and approved image version from your staging environment should go live. The SHA digest removes ambiguity about the deployed artefact. You can find it in your GitHub Actions build logs or Azure Container Registry.

Example SHA Digest:

sha256:a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890

Actions:

• After successful WASA and your final testing on staging, locate the SHA digest of the specific Docker image that embodies these approved changes.
• Communicate this exact SHA digest to the DSF team.

What to do: After all required prerequisites are met and approved (WASA passed, DPIA approved, production secrets file provided, and the specific production image SHA digest identified), the DSF team will manually review (including DLL vulnerabilities) and then proceed with the deployment of your application to the production environment.

Why it’s important: This manual step ensures a final review and approval before critical production systems are affected. It allows the DSF team to perform necessary checks, coordinate with other teams if needed, and execute the deployment with controlled precision, minimizing risk to live services.

Actions:

• Notify the DSF team that your application has passed WASA, the DPIA is approved, and you have provided the production secrets file and the specific image SHA digest (from Stage 2, Steps 1-4).
• Make sure that the repository does not contain any vulnerabilities (check Dependabot report)
• The DSF team will then schedule and execute the production deployment.
• The DSF team will confirm once your application is successfully deployed to the production environment.

---

Once your application is deployed to production, it’s crucial to maintain clear documentation for ongoing support, future development, and knowledge transfer. These documents help ensure your application remains maintainable and understandable for anyone who needs to work with it.

Managing vulnerabilities is crucial for the security of the DSF infrastructure. The service owner is responsible for identifying and resolving vulnerabilities in the GitHub repository during the entire lifecycle of the application. Dependabot is a GitHub tool that automatically scans your repositories to ensure they remain current and secure.
Consult the Security and Risk Management Section of the Service Delivery Team Onboarding and Service Delivery Guide for more information and the timeframe table for vulnerability resolution:

What to do: Ensure that a comprehensive README.md file is present in the root of your GitHub repository. This file should serve as the primary entry point for anyone looking to understand, set up, or contribute to your application.

Why it’s important: A well-documented README provides essential information at a glance, including:

• A brief description of the application’s purpose and functionality.
• Instructions for local development setup (dependencies, environment variables, how to run tests).
• Key architectural decisions or dependencies.
• Contact information or support channels for your team.

Actions:

• Create or update the README.md file in the root of your repository.
• Ensure it contains all necessary information for someone unfamiliar with the project to get started.
• Commit and push the README.md file to the master (or main) branch.

What to do: Include a CHANGELOG.md file in the root of your GitHub repository. This file should document all significant changes made to the application, organized by version and release date.

Why it’s important: A changelog provides a chronological record of changes, making it easier to:

• Track new features, bug fixes, and performance improvements. 
• Make sure to frequently monitor and resolve any vulnerabilities in your application (GitHub dependabot report), especially Critical and High severity issues, ensuring it meets our security standards.
• Understand the history of the application’s development.
• Facilitate communication about releases to stakeholders and other teams.
• Aid in debugging by pinpointing when certain changes were introduced.

Actions:

• Create or update the CHANGELOG.md file in the root of your repository.
• Ensure it is kept up to date with each significant change or release.
• Resolve any vulnerabilities in your application
• Commit and push the CHANGELOG.md file to the master (or main) branch.

---

By following these comprehensive steps, your team can efficiently and securely deploy and update your web applications on our AKS private clusters, ensuring all necessary quality and compliance gates are met for production readiness. If you have any questions or encounter issues at any stage, please reach out to the DSF team.

Relevant Content

• User Satisfaction Page Guide
• Service Delivery Team Onboarding and Service Delivery Guide
• Matomo on-premise
• Testing Process for a Digital Service
• Design System