Getting Started
Getting Started
Now that you have a basic understanding of what pipelines are, let's get started with a simple example. As mentioned in the previous page, we will create a pipeline that is used to create this documentation site. This site is created with vuepress, a static site generator for vue.js. It's great for creating documentation sites, and it's pretty straightforward to get started with.
You can find the source code for this site on gitlab.
To start off this journey we'll have to take a look at the .nosana-ci.yml
file that is used to configure this pipeline. You should be able to find it in the root of the repository.
Yaml is a human readable data serialization format that is commonly used for configuration files. It's easy to read and write, and it's supported by most programming languages. It's the standard for configuring ci/cd pipelines on gitlab, github and other popular code hosting platforms. You can find more information about yaml here.
Let's take a look at the .nosana-ci.yml
file for this site: To begin with there are 3 top level definitions that are used to configure the pipeline: nosana
, global
, and jobs
. The nosana
section is used to configure the pipeline itself, and the global
section is used to configure the environment that the pipeline will run in. The jobs
section is used to configure the individual jobs that will be executed in the pipeline.
nosana
We'll explore the nosana
section first.
# .nosana-ci.yml
nosana:
# the name of the nosana pipeline
description: build and deploy the nosana documentation site
...
description
: the name of the pipeline. this is used to identify the pipeline in the nosana network.
global
The global
section is used to configure the environment that the pipeline will run in. this includes the image that will be used to run the pipeline, and the environment variables that will be available to the pipeline. it is possible to define the image in the global
section, or in the jobs
section. this is useful if you want to use a different image for each job. if the image is not defined in the jobs section, the image defined in the global
section will be used. market
the Solana address of the Nosana market that will be used to pay for the pipeline.
...
# global settings
global:
# image used to run the pipeline
image: registry.hub.docker.com/library/node:16
# event that will trigger the pipeline.
trigger:
branch:
- main
- develop
# environment variables that will be available to the pipeline
environment:
APP_ENV: production
APP_DEBUG: false
# allow the pipeline to abort if one of the commands returns a failure state.
allow_failure: true # false
...
market
: the solana address of the nosana market that will be used to pay for the pipeline.image
: the image that will be used to run the pipeline. this can be any docker image that is available on docker hub. the image will be pulled from docker hub when the pipeline is executed. If the image is not defined in thejobs
section, the image defined in theglobal
section will be used. Note the format of the resource identifier used when pulling down an image:registry.hub.docker.com/user/image:tag
ordocker.io/user/image:tag
. More information about docker images can be found here.trigger
: the event that will trigger the pipeline. this can be a branch, tag, or a schedule.image
: the image that will be used to run the pipeline. this can be any docker image that is available on Docker hub. the image will be pulled from docker hub when the pipeline is executed. If the image is not defined in thejobs
section, the image defined in theglobal
section will be used. Note the format of the resource identifier used when pulling down an image:registry.hub.docker.com/user/image:tag
ordocker.io/user/image:tag
. More information about docker images can be found here.trigger
: the event that will trigger the pipeline. this can be a branch, tag, or schedule.branch
: the pipeline will be triggered when a commit is created on the specified branch.
environment
: environment variables that will be available to the pipeline.allow_failure
: allow the pipeline to abort if one of the commands returns a failure state.
Now that we've managed to get a basic understanding of the .nosana-ci.yml
file, let's take a look at the individual jobs that are defined in the jobs
section.
jobs
The jobs
section is used to configure the individual jobs that will be executed in the pipeline. Each job is defined by a name and a set of commands that will be executed in the job. The commands are executed in the order that they are defined in the job.
Job configuration
Just like it is possible to define the image in the global
section, it is also possible to define the configuration for each job in the jobs
section. This is useful if you want to use a different image for each job, or if you want to use a different set of environment variables for each job.
When the image is defined in the jobs
section, it will override the image defined in the global
section. On top of this intricacy, it is also possible to specify the configuration per command.
Note that the configuration defined per job is optional. If the configuration is not defined, the configuration defined in the global
section will be used. For more information, you can take a look at the specification.
Let's take a look at the following example break it down and figure out what is happening: For this example let's take a look at the jobs
section of our example:
...
# Node V18
- name: setup-node_18
image: registry.hub.docker.com/library/node:18
environment:
APP_ENV: production
APP_DEBUG: false
commands:
- npm ci
artifacts:
- name: node_modules
path: ./node_modules/
- name: generate-docs_18
commands:
- npm run build
resources:
- name: node_modules
path: ./
artifacts:
- name: dist_folder
path: ./dist/
...
name
: the name of the job. this is used to identify the job in the Nosana network.commands
: the shell commands that will be executed in the job.artifacts
: the artifacts that will be generated by the job.name
: the name of the artifact.path
: the path to the artifact.
resources
: the resources that will be available for the job.name
: the name of the resource.path
: the path for where to place the resource.
In the example above we have defined 2 jobs: setup-node
and generate-docs
. The setup-node
job will install the dependencies for the project, and the generate-docs
job will generate the documentation site. The setup-node
job will generate an artifact called node_modules
, and the generate-docs
job will generate an artifact called dist_folder
. The generate-docs
job will also use the node_modules
artifact that was generated by the setup-node
job.
So it is important to keep in mind that the artifacts that are generated by one job can be used by another job. this is useful if you want to share data between jobs. Eventually, this is useful to produce an artifact that will be deployed to production. in this case that would be the dist_folder
artifact, which contains a static HTML with some as
env
Nosana will inject environment variables for you into your pipeline so that you can have some information about your COMMIT_SHA
. Other environmental variables that are injected are there to try to create colored output for your logs.
The environment variables listed will be injected into a CI/CD pipeline as global environment variables. This means that they will be accessible to you throughout the execution of the pipeline as environment variables. you can then reference these variables in their pipeline configuration and scripts to perform actions based on the information provided by the variables. For example, you can use the echo $NOS_COMMIT_SHA
to print out the commit SHA of the current pipeline execution, or the $NOS_REPO_NAME
variable to reference the name of the repository associated with the pipeline.
TERM
- For color output, default value:1
FORCE_COLOR
- For color output, default value:1
CLICOLOR
- For color output, default value:1
NOS_COMMIT_SHA
- Git commit SHAn, that triggers this jobNOS_REPO_ID
- Nosana repo uuidNOS_REPO_NAME
- Git repository nameNOS_USER_ID
- Nosana user uuidNOS_MARKET_ADDRESS
- Nosana market address