User Guide

Introduction

This section provides an in-depth overview of the platform focusing on users accessing, navigating and interacting with the platform efficiently.

CODE-IDP Homepage

You can sign in using your code email or github account email.

Note

As this is an ongoing experimental project, you may need to refresh browser if page doesn't load properly.

Getting Started

CODE-IDP is the platform to automate deployment of node and flask applications, centralize software components(Microservices, Websites, Libraries, APIs, Data pipelines, ML models ) and publish technical documentation.

Current components defined can be found in the Catalog home

How to Deploy Your Nodejs and Flask Applications

Before you can proceed, we need a few things from you:

1. Your Github Repository

You need to provide the name of your repository: https://github.com/your-user-name/your-repo-name

2. Your Database Credentials

You also need to provide your MongoDB database string: mongodb+srv://<your-user-name>:<your-password>@<your-cluster-name>.nhn6ohr.mongodb.net/

3. Environment Variables

Your Mongo database string contains sensitive information, such as your password and your You should make a habit of storing sensitive information, such as the database string, which, among other things, includes your password, in environment variables. A not so gentle reminder: Ensure your .env file is added to your .gitignore to prevent it from being uploaded to version control systems like Git.

DB_URI=your_mongodb_connection_string
DB_NAME=your_database_name

For more on environment variables, and why they are important, check out this article.

If your connection string contains special characters, as your password most likely will, you need to put it in quotation marks in your .envfile.

DB_URI="your_mongodb_connection_string"
DB_NAME="your_database_name"

While you could leave out quotation marks for anything that does not contain special characters, you should use them anyway, just to avoid unnecessary error messages later on.

Register Your Software Component

You need the following things to register a component

• A repository on GitHub or Gitlab
• A file name catalog-info.yaml in the root of the repository

Define your catalog-info.yaml file

Create the catalog-info.yaml file and set the values of kind (Component) name, description, type(service), lifecycle and owner

apiVersion:backstage.io/v1alpha1
kind: Component
metadata:
    name: name-of-service
    description: Short description of your service
    # If you want to view github workflow actions on backstage
    github.com/project-slug: '<username>/<repository>'
    # If you want backstage to generate your markdown docs to view in backstage
    backstage.io/techdocs-ref: dir:
spec:
    type: service
    lifecycle: development or production or experimental
    owner: name_of_team or individual # Use an underscore to separate words for your team name

• Register the component in Backstage

1. Click Create and then go to Register an existing component section, paste the URL of the catalog-info.yaml file in your repository (E.g. ``)
2. Click ANALYZE, review and confirm the import with the button IMPORT.
3. Your component configuration will be imported.

!!! success Your component should be now available in the Catalog home.

How to publish your documentation

You need the following things prepared to document a component:

• A registered component (You can also do both setups, registration of the component and the documentation together in one go).

Set the configuration file for MkDocs

• A file named mkdocs.yml in the root of the repository.

!!! example "mkdocs.yml file with techdocs configuration"

```yaml
site_name: Publish Documentation Example
docs_dir: docs
plugins:
- techdocs-core
```

Add annotation for documentation

You need to create the definition annotations: inside the metadata: section of your component and add the key backstage.io/techdocs-ref annotation in the catalog-info.yaml file.

!!! example "catalog-info.yaml file with techdocs information"

```yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  #...
  annotations:
    backstage.io/techdocs-ref: dir:.
  #...
```

Add documentation

Create a directory called docs, define a file called index.md or readme.md, this will be the main page of your documentation.

Inside this docs directory you should be able to use Markdown files *.md to define your documentation.

Formatting and capabilities

Documentation is formatted mainly using MkDocs syntax, also with Material for MkDocs features and some specific features added to Backstage as plugins.

Reference

• Register a Component
• TechDocs Documentation in Backstage