This page has been replicated to a publicly accessible website located here
| Status | GreenPublished |
|---|---|
| Overview | The purpose of this page is to outline some of the key information and connections that product teams should be made aware of as part of team inception. This is a living and collaborative document. Teams can use this page a reference point to assist in locating some key areas of information related to their application. If the information you are using does not exist here please review other guideline pages and/or contact the architecture team. |
Partnership Agreement
NRM teams that work within our Development and Digital Services (DDS) branch start with a partnership agreement to ensure alignment between NRIDS and the program area.
NRM Digital Service Delivery Partnership Agreement
Team Agreement
Before starting development, or when new team members begin contributing, ensure everyone on the team has the same understanding about coding practices, technology choices, and roles within your team. This is typically done during sprint 0.
Product Lifecycle
Is your team replacing, re-architecting or re-platforming an existing application? If so, it's the Product Owner's responsibility to ensure the existing application is retired and the data is transitioned or preserved to ensure data quality, accuracy and currency as well as overall portfolio sustainability. Product Owners may reach out to their assigned Ministry Portfolio Manager (MPM) for assistance with the Application Retirement process.
Ensure you allocate time and budget in your backlog to manage the overall lifecycle of the business processes, data and associated products.
Helpful links on Application Retirement:
Private Cloud
The BC Government has invested heavily in the Red Hat OpenShift platform to provide self service private cloud capabilities. Training is available through the exchange lab to get teams acquainted with the platform; a good primer is here.
https://developer.gov.bc.ca/ExchangeLab-Course:-OpenShift-101
The landing page for the private cloud service is here: https://cloud.gov.bc.ca/private-cloud/
Namespace provisioning can be found here: https://registry.developer.gov.bc.ca/public-landing
Information on resource tuning for OpenShift Namespaces can be found here: https://beta-docs.developer.gov.bc.ca/application-resource-tuning/
The RedHat learning portal is a great resource to learn more about the platform, and they also provide a sandbox to 'learn by doing'.
Some of the more important concepts to understand up front are:
- Image streams, builds & tagging
- Network policy settings to allow pods to communicate internally and to the web via routes,
- How to get deployments to listen to tags and/or configuration changes (eventually on repo events like pull requests)
- Tuning, health checks, resource allocation and tuning, and pod scaling
OpenShift QuickStart Application
Our friends and collaborators in Forestry Digital Services and the Architecture team have created an application template that includes pluggable API backends (Node/Nest, Python/FastAPI, Go/Fiber, Java/Quarkus) and frontend (React, Vite), with a deployment pipeline to the OpenShift platform with an option to include a PostgreSQL/PostGIS database and leveraging the backup container provided by the BC DevExchange. This is a great resource to get product teams up and running.
Public Cloud
BC Government has endorsed several public cloud services and provides quickstart guides and sample applications!
Approved AWS services can be found here: https://developer.gov.bc.ca/AWS-Services
GitHub
Source code should be stored in a GitHub repository in the "bcgov" tenancy.
Access management for the bcgov GitHub tenancy can be found here: https://just-ask.developer.gov.bc.ca/
NRM specific guidance on Github is here: Source Code Repositories
Authentication and Identity
Most NRM digital products leverage the OCIO SSO service that is backed by Keycloak.
https://bcgov.github.io/sso-requests
Secrets Management
The platform services team operates a Vault service.
It is described here: https://beta-docs.developer.gov.bc.ca/vault-secrets-management-service/
Access to the service is here: https://vault.developer.gov.bc.ca/ui/vault/auth?with=token
Security and Privacy
It's important that teams engage with the NRM Security and Privacy teams early and often. They can support you with general advice as well as Security Threat Risk Assessments (STRA's) and Privacy Impact Assessments (PIA's).
NRM Security Knowledge Base: NRM Information Security Home
NRM Privacy Knowledge Base: NRM Privacy Knowledge Base
OWASP (Open Web Application Security Project) is another great reference for security best practices for development teams: https://owasp.org/www-project-secure-coding-practices-quick-reference-guide/migrated_content
CI/CD
The deployment pipeline is a key component for your application. For visibility, collaboration and maintainability modern teams are moving away from Jenkins towards GitHub actions.
It is strongly recommended that code be submitted using a Pull Request. Automated testing can and should replace manual UAT wherever practical.
NRM has a modern CI/CD template using GitHub Actions and HELM: OpenShift QuickStart targeted for OpenShift Silver or Gold Cluster.
NRM has a modern CI/CD template using GitHub Actions, HELM and Argo: OpenShift QuickStart Emerald targeted for OpenShift Emerald Cluster.
Application Programming Interfaces (API's)
We recommend adopting an "API First" philosophy for application development, where teams both build and consume their API's. Providing API specification with proper metadata is mandatory irrespective of the underlying implementation(REST, graphql, grpc etc..)
Along with API first approach the Architecture team highly recommends looking at Domain Driven Design(DDD) where each micro-service API is bounded by its business domain(https://martinfowler.com/bliki/DomainDrivenDesign.html)
Also look at Event-Driven Architecture (Event Sourcing and CQRS) when building micro-services as it promotes highly decoupled APIS, communicating over an event streaming platform (https://microservices.io/patterns/data/event-sourcing.html, https://microservices.io/patterns/data/cqrs.html)
We recommend a Test Driven Development (TDD) approach to API development, as it makes the application code more reliable and efficient along with easier maintenance in the future.
There are several ways to name test methods/functions but we recommend using the pattern test<method_name>_<given_condition>_<expected_behavior>, it makes the tests more readable, predictable and becomes living documentation of the codebase.
BC Government has published a set of API Guidelines here: https://developer.gov.bc.ca/Data-and-APIs/BC-Government-API-Guidelines
Information on the corporate API gateway can be found here: https://bcgov.github.io/aps-infra-platform/
Database and Data Design
Most of the teams working on OpenShift are choosing a flavor of PostgreSQL to persist data for their application.
Some points of consideration are:
- What type of data are you persisting as part of your application? Are you storing geospatial data? Audio and/or video?
- What are your preferred integration patterns?
- Do you have any requirements, for example, to replicate data to the BC Geographic Warehouse (BCGW)?
- What are the requirements for consistency, availability and partitioning?
For NRM guidance specific to data and database design, please visit this space: NRM Data and Database Development Guidelines
Database backups can be setup using the backup container image; information can be found here: https://developer.gov.bc.ca/Backup-Container
Indigenous Languages: the BC Government is committed to including Indigenous languages in government records, systems and services. The BC Sans font is an open-source "living" typeface developed for government to improve the readability and delivery of digital services. It was designed to support special characters and syllabics found in Indigenous Languages in B.C. When designing and building your product, ensure it has the ability to collect, store, manage and display BC Sans characters. Connect with your architects for more details and references.
Document Storage
BC Government has an on premise object storage solution that delivers low cost storage for unstructured and semi-structured data. The service is billed monthly to the highwatermark of the storage your team consumes in their S3 bucket at $0.07/GB/Month. To get an S3 object storage bucket, contact the Optimize team.
COMS (Common Object Management Service) is an emerging common component that leverages the object storage solution. The advantage of this component is that it includes the ability to tag and add metadata, and integrates with BC Government's standard identity providers (IDIR, BCeID). To learn more, attend the Common Services Showcase team sprint reviews or contact the team via email.
An emerging companion to the Common Object Management Service being built by the Common Services team is BCBox, which is a hosted solution that uses the COMS API to allow users to upload, tag and share files using any OIDC compliant authentication mechanism. The code repository for BCBox can be found here.
Design Guidance
General resources for Agile designers at Digital Government (BC Visual Identity, Official BC Design System, Web Style Guide, Content Design Guidance, UX Research Guidance, Service Design Playbook) can be found here:
https://digital.gov.bc.ca/resources#:~:text=Read%20the%20playbook-,For%20Designers,-B.C.%20Visual
Additional design system guidance: https://developer.gov.bc.ca/Design-System/About-the-Design-System
BC Parks has extended their Design Guide to include the use of the BC Sans font and other additions specific to their program:
https://bcgov.github.io/bcparks/design-guides
Front End Frameworks
Many agile teams are using a flavor of Javascript framework for their front end development (Angular, Vue, React etc). We recommend you pick the framework that works best for the team, and if you are developing a suite of applications for your program area, harmonize across the suite where that makes sense. This will minimize risk associated with changes to the team and enable other developers to work with your code.
Web Mapping Frameworks
A comparison of web mapping frameworks in use in BC Government can found here: https://bcgov.github.io/bcwebmaps-options/
Back End Languages
Similar to front end frameworks, we recommend you choose a development language that best suits the team and the business challenge you are working on. If you are developing a suite of applications for your program area, harmonize across the suite where that makes sense. This will minimize risk associated with changes to the team and enable other developers to work with your code.
There are many languages in use by agile teams across government, the most popular being Go, Python, Java, Javascript and Typescript. The Technology Radar is a great reference to see where the momentum is around languages and frameworks.
Web Domains and Certificates
Information on NRM Web Domains can be found here: Web-Application domains
An example of a public facing URL is https://fom.nrs.gov.bc.ca/public/projects
Information on how to obtain an SSL certificate can be found here: Automation of TLS Certificates for Websites
Further information on security certificates can be found here: Security Certificates
Information on certbot can be found here: https://github.com/BCDevOps/certbot
Common Components
BC Government has a selection of mature common components and common services.
Digital Government reference: https://digital.gov.bc.ca/common-components
NRM Specific Guidance: Common Components and Common Services
Community Tip! If you are looking for a common component you think should exist, but doesn't, consider adding some extra design thinking such that other teams can reuse your great work!
Reporting and Analytics
Many teams require reporting and analytics capabilities for their application data. Metabase is an easy-to-use open-source dashboarding and business intelligence tool that has broad usage in the NRM. Architecture has created a packaged install of Metabase tailored to teams wanting secure access to Zone B Oracle databases.
I need help from the Community!
There are many teams working across the NRM and beyond. To connect with your NRM colleagues, see the team directory here NRIDS Development and Digital Services
The community uses Rocket.Chat to solicit help from other teams on all sorts of subjects. Users can authenticate with IDIR or their GitHub ID.
https://chat.developer.gov.bc.ca/
Channels of interest might include #general #devops-alerts #devops-operations #nr-iitd-agile-teams and any channel prefixed with "#nr-"
The NRM teams have a DevOps Guild to facilitate connections and collaboration between teams: https://apps.nrs.gov.bc.ca/int/confluence/display/DEVGUILD
You can also reach out to the NRM Architecture team, who can help connect your team with the right resources.
Key References:
BC DevHub: https://developer.gov.bc.ca, https://docs.developer.gov.bc.ca/
Common Components: https://digital.gov.bc.ca/common-components
Communities of Practice: https://digital.gov.bc.ca/communities
BC Gov StackOverflow: https://stackoverflow.developer.gov.bc.ca/
FAQ
Q. Do I need my application and data architecture to be formally approved?
A. No, there is no formal approval process for your architecture. We recommend collaborating with the architecture team during any architectural spikes or any significant architectural decisions. Our collective experience and connectedness across the community can typically provide value for the team.
Q. Do I have to use OpenShift to host my application?
A. No. We would generally like new applications to be running in a containerized or serverless hosting architecture. OpenShift is a strong option for teams starting out given the maturity of the platform and the surrounding community, as is the AWS Public Cloud Service, both operated by BC Government teams. Following cloud native design principles will help ensure that your application workload is portable between hosting platforms.
Q. Can I pass my application off to an ops team so the team can work on new apps?
A. We generally follow the "you build it, you run it" philosophy, and therefore recommend you build a sustainment plan into your application roadmap. Adhering as closely as possible to the 12 Factor principles is a great way to promote a sustainable, cloud native build.