NAV
bash

Introduction

Welcome to the Octo! You can use this tools to register and display all applications versions of your compagny for each client and platform.

Installation

Octo is composed of three components:

Docker

Build octo-spy and octo-board docker images:

docker build -t octo-spy octo-spy/

docker build -t octo-board octo-board/

To use Octo with docker you must build octo-spy and octo-board images.

Once images build, you can setup your environment like the compose example.

Don't forget to setup volume for database.

Other

If you didn't have a proper docker environment. You can build octo-spy and octo-board and deploy them on associated service.

Build octo-spy

Command to build octo-spy, run it in ./octo-spy folder

mvn clean package -Dmaven.test.skip=true

To build octo-spy you need java 16 and maven 3.8.1 on your building machine.

You can find the associated war in target folder. And you can deploy it on Tomcat (v9.0.52).

Build octo-board

Commands to build octo-board, run it in ./octo-board folder

# Install project dependencies
npm install --legacy-peer-deps

# Build changelog page and json
npm run changelog --silent > public/changelog.html
RUN npm run changelogToJson

# Build project
npm run build

To build octo-board you need node 14.17.X and npm 7.20.X on your building machine.

You can find the associated war in build folder. And you can deploy it on your wanted HTTP server.

Configuration

Default user

Default administrator login is admin with admin as password and has no-reply@change.it as default e-mail.

Database connection

Default user login is octo. Default user password is password.

You can override application settings with environment variable:

Variable name default value Description
octo-spy.database.host localhost Database address.
octo-spy.database.port 5432 Database port.
octo-spy.database.name octo_db Database name.
octo-spy.database.username octo Database user login.
octo-spy.database.password password Database user password.

Usages

Authentication

Basic authentication

Authentication example to get user information

curl                                           \
  --header "Authorization: Basic BASE64_TOKEN" \
  --request GET                                \
  http://spy:8080/octo-spy/api/users/me

You need to encode in base64 your user:password.

Token authentication

Authentication example to get user information

curl                                           \
  --header "Authorization: Token TOKEN" \
  --request GET                                \
  http://spy:8080/octo-spy/api/users/me

You need to use token given by application when you create a token.

Create master and sub-project

Go to octo-board, as administrator go to master project page, to create master project.

To create sub-project, still as administrator, go to master project page and go to sub-project page.

Register in progress deployment

Register new in progress deployment for octo-spy version 1.0.0 in production for SomeClient

curl                                           \
  --header "Authorization: Basic BASE64_TOKEN" \
  --header "Content-Type: application/json"    \
  --request POST                               \
  --data 'DATA_TO_SEND'                        \
  http://spy:8080/octo-spy/api/deployments

Data to send:

{
  "environment": "Production",
  "project": "octo-spy",
  "version": "1.0.0",
  "client": "SomeClient",
  "alive" : true,
  "inProgress": true
}

A deployment is a record of new version on a project for a specific environment.

Default environments:

You can directly indicate if your deployment is in progress or not.

Stop progress of a deployment

Delete progress state for octo-spy version 1.0.0 in production for SomeClient

curl                                           \
  --header "Authorization: Basic BASE64_TOKEN" \
  --header "Content-Type: application/json"    \
  --request DELETE                             \
  --data 'DATA_TO_SEND'                        \
  http://spy:8080/octo-spy/api/deployments/progress

Data to send:

{
  "environment": "Production",
  "project": "octo-spy",
  "version": "1.0.0",
  "client": "SomeClient",
  "alive" : true
}

At the end of deployment you can indicate, that is done by deleting the progress state.

API documentation

Default object

Default resource object:

{
  "total": 0,
  "page": 0,
  "count": 0,
  "resources": []
}
Key Type Description
total Number Total of resources in database
page Number Current index of pagination
count Number Length of resources, maximum 200
resources Array Array of wanted resource

Default error object:

{
  "message": null,
  "field": null,
  "value": null,
  "cause": null
}
Key Type Description
message String Generic error's message.
field String Field name where error occurs
fields String Field name where error occurs
value String Field value or error explanation
cause String Stack trace of the error.

Query filter explanation

On some endpoints, you can use search field to filter your resources.

You have 4 types of search: TEXT, DATE, NUMBER and BOOLEAN.

Default modifier

There is a modifier that can be applied on all searches types:

Input date format: yyyy-MM-dd HH:mm:ss

Ouput date format: yyyy/MM/dd HH:mm:ss

Authentication's errors

Apply for all endpoint that need authentication.

Administrator

Update administrator password

Update administrator password

curl                                           \
  --header "Authorization: Basic BASE64_TOKEN" \
  --request PUT                                \
  --data 'BASE64_PASSWORD'                     \
  http://spy:8080/octo-spy/api/administrator/password

Update administrator e-mail

Update administrator e-mail

curl                                           \
  --header "Authorization: Basic BASE64_TOKEN" \
  --request PUT                                \
  --data 'EMAIL'                               \
  http://spy:8080/octo-spy/api/administrator/email

Alerts

Get all application alerts

Get all application alerts

curl                                           \
  --header "Authorization: Basic BASE64_TOKEN" \
  --request GET                                \
  http://spy:8080/octo-spy/api/alerts

Example of success:

{
  "total": 1,
  "page": 0,
  "count": 1,
  "resources": [{
    "severity": "critical",
    "type": "security",
    "message": "Administrator's password is not secure, please change it."
  }]
}
Key Type Description
severity String Indicates severity of alert (critical or warning)
type String Indicates type of alert (security or incompatible)
message String Explanation of alert

There is only 3 alerts:

Client

Get all clients

Get all application clients

curl                                  \
  --request GET                       \
  http://spy:8080/octo-spy/api/clients

Example of success:

["Client1", "Client2"]

Deployment

Get deployment by id

Get deployment by id

curl                                  \
  --request GET                       \
  http://spy:8080/octo-spy/api/deployments/[id]

Example of success:

{
  "id": 0,
  "environment": null,
  "project": null,
  "masterProject": null,
  "client": null,
  "version": null,
  "alive": true,
  "insertDate": null,
  "updateDate": null
}
Key Type Description
id Number Primary key
environment String Environment name
project String Project name
masterProject String Master project name
client String Client name
version String Deployed version
alive Boolean is still alive.
insertDate Date Creation date, format: yyyy/MM/dd HH:mm:ss
updateDate Date Last update date, format: yyyy/MM/dd HH:mm:ss

Get all deployments

Get all deployments

curl                                  \
  --request GET                       \
  http://spy:8080/octo-spy/api/deployments

Example of success:


{
  "total": 1,
  "page": 0,
  "count": 1,
  "resources": [{
    "id": 0,
    "environment": null,
    "project": null,
    "masterProject": null,
    "client": null,
    "version": null,
    "alive": true,
    "insertDate": null,
    "updateDate": null
  }]
}

Available query parameters:

Field name Search type
id NUMBER
environment TEXT
project TEXT
masterProject TEXT
client TEXT
version TEXT
alive BOOLEAN
inProgress BOOLEAN

Get last deployments

Get last deployments

curl                                  \
  --request GET                       \
  http://spy:8080/octo-spy/api/deployments/last

Example of success:


{
  "total": 1,
  "page": 0,
  "count": 1,
  "resources": [{
    "id": 0,
    "environment": null,
    "project": null,
    "masterProject": null,
    "client": null,
    "version": null,
    "alive": true,
    "insertDate": null
  }]
}

Available query parameters:

Field name Search type
id NUMBER
environment TEXT
project TEXT
masterProject TEXT
client TEXT
version TEXT
alive BOOLEAN
inProgress BOOLEAN
onMasterProject BOOLEAN

Create a deployment

Create a deployment

curl                                           \
  --header "Authorization: Basic BASE64_TOKEN" \
  --header "Content-Type: application/json"    \
  --request POST                               \
  --data 'DATA_TO_SEND'                        \
  http://spy:8080/octo-spy/api/deployments

Example of data to send:

{
  "environment": "Production",
  "project": "octo-spy",
  "client": "SomeClient",
  "version": "1.0.0",
  "alive" : true,
  "inProgress" : true
}

Example of success:

{
  "id": 1,
  "environment": "Production",
  "project": "octo-spy",
  "masterProject": null,
  "client": "SomeClient",
  "version": "1.0.0",
  "alive": true,
  "insertDate": null,
  "updateDate": null
}

Body parameters:

Key Type Mandatory Description
environment String Yes Environment name
project String Yes Project name
client String Yes Client name
version String Yes Deployed version
alive Boolean No, default false Is still alive.
inProgress Boolean No, default false Is in progress.

Update a deployment

Update a deployment

curl                                           \
  --header "Authorization: Basic BASE64_TOKEN" \
  --header "Content-Type: application/json"    \
  --request PATCH                              \
  --data 'DATA_TO_SEND'                        \
  http://spy:8080/octo-spy/api/deployments/[id]

Example of data to send:

{
  "environment": "Production",
  "project": "octo-spy",
  "client": "SomeClient",
  "version": "1.0.0",
  "alive" : true,
  "inProgress" : true
}

Body parameters:

Key Type Mandatory Description
environment String Yes Environment name
project String Yes Project name
client String Yes Client name
version String Yes Deployed version
alive Boolean No, default false Is still alive.
inProgress Boolean No, default false Is in progress.

Delete progress of a deployment

delete a deployment

curl                                           \
  --header "Authorization: Basic BASE64_TOKEN" \
  --request DELETE                             \
  --data 'DATA_TO_SEND'                        \
  http://spy:8080/octo-spy/api/deployments/progress

Example of data to send:

{
  "environment": "Production",
  "project": "octo-spy",
  "client": "SomeClient",
  "version": "1.0.0",
}

Available body parameters:

Field name Search type Mandatory
id NUMBER No
projectId NUMBER No
environment TEXT Yes
project TEXT Yes
masterProject TEXT No
client TEXT No
version TEXT No
alive BOOLEAN No
inProgress BOOLEAN No

Environment

Get all environments

Get all application environments

curl                                  \
  --request GET                       \
  http://spy:8080/octo-spy/api/environments

Example of success:

[
  {
    "id": 1,
    "name": "Production",
    "position": 0
  }
]
Key Type Description
id Number Primary key
name String Environment name

Create an environment

Create an environment

curl                                           \
  --header "Authorization: Basic BASE64_TOKEN" \
  --header "Content-Type: application/json"    \
  --request POST                               \
  --data 'DATA_TO_SEND'                        \
  http://spy:8080/octo-spy/api/environments

Example of data to send:

{
  "name": "Production",
  "position": 1
}

Example of success:

{
  "id": 1,
  "name": "Production",
  "position": 1
}

Body parameters:

Key Type Mandatory Description
name String Yes Environment name
position Integer No Order of environment

Update an environment

Update an environment

curl                                           \
  --header "Authorization: Basic BASE64_TOKEN" \
  --header "Content-Type: application/json"    \
  --request PATCH                              \
  --data 'DATA_TO_SEND'                        \
  http://spy:8080/octo-spy/api/environments/[id]

Example of data to send:

{
  "name": "Production",
  "position": 1
}

Body parameters:

Key Type Mandatory Description
name String No Environment name
position Integer No Order of environment

Delete an environment

delete an environment

curl                                           \
  --header "Authorization: Basic BASE64_TOKEN" \
  --request DELETE                             \
  --data 'DATA_TO_SEND'                        \
  http://spy:8080/octo-spy/api/environments/[id]

Example of data to send:

{
  "environment": "Production",
  "project": "octo-spy",
  "client": "SomeClient",
  "version": "1.0.0",
}

Application information

Get application information

curl                                  \
  --request GET                       \
  http://spy:8080/octo-spy/api/info

Example of success:

{
  "project": null,
  "version": null,
  "environment": null,
  "client": null
}
Key Type Description
environment String Environment name
project String Project name
client String Client name
version String Deployed version

Project

Get project by id

Get project by id

curl                                  \
  --request GET                       \
  http://spy:8080/octo-spy/api/projects/[id]

Example of success:

{
  "id": 0,
  "name": null,
  "insertDate": null,
  "updateDate": null
}
Key Type Description
id Number Primary key
name String Project name
insertDate Date Creation date, format: yyyy/MM/dd HH:mm:ss
updateDate Date Last update date, format: yyyy/MM/dd HH:mm:ss

Get all projects

Get all projects

curl                                  \
  --request GET                       \
  http://spy:8080/octo-spy/api/projects

Example of success:


{
  "total": 1,
  "page": 0,
  "count": 1,
  "resources": [{
    "id": 0,
    "name": null,
    "insertDate": null,
    "updateDate": null
  }]
}

Available query parameters:

Field name Search type
id NUMBER
name TEXT

Update a project

Update a project

curl                                           \
  --header "Authorization: Basic BASE64_TOKEN" \
  --header "Content-Type: application/json"    \
  --request PATCH                              \
  --data 'DATA_TO_SEND'                        \
  http://spy:8080/octo-spy/api/projects/[id]

Example of data to send:

{
  "name": "octo",
  "color": "12,23,199"
}

Body parameters:

Key Type Mandatory Description
name String No Project name
color String No Color of project, format 'R,G,B' where R/G/B is insteger between 0 and 255

Create a project

Create a project

curl                                           \
  --header "Authorization: Basic BASE64_TOKEN" \
  --header "Content-Type: application/json"    \
  --request POST                               \
  --data 'DATA_TO_SEND'                        \
  http://spy:8080/octo-spy/api/projects

Example of data to send:

{
  "name": "octo",
  "isMaster": true,
  "masterName": null,
}

Example of success:

{
  "id": 1,
  "name": "octo",
  "insertDate": null,
  "updateDate": null
}

Body parameters:

Key Type Mandatory Description
name String Yes Project name
isMaster Boolean No, default false Is master project
masterName String No Master project name

Delete a project

delete a project

curl                                           \
  --header "Authorization: Basic BASE64_TOKEN" \
  --request DELETE                             \
  http://spy:8080/octo-spy/api/projects/[id]

Report

Deployments

Deployments report

curl                                  \
  --request GET                       \
  http://spy:8080/octo-spy/api/report/deployments

Example of success:

[{
  "id": 0,
  "masterProject": null,
  "project": null,
  "environment": null,
  "client": null,
  "year": 0,
  "month": 0,
  "dayOfWeek": 0,
  "day": 0,
  "hour": 0,
  "count": 0
}]

Available query parameters:

Field name Search type
id NUMBER
masterProject NUMBER
project NUMBER
environment NUMBER
client TEXT
year NUMBER
month NUMBER
dayOfWeek NUMBER
day NUMBER
hour NUMBER

User

Get my information

Get my information

curl                                           \
  --header "Authorization: Basic BASE64_TOKEN" \
  --request GET                                \
  http://spy:8080/octo-spy/api/users/me

Example of success:

{
  "user": {
    "login": null,
    "firstname": null,
    "lastname": null,
    "email": null,
    "active": true,
    "insertDate": null,
    "updateDate": null
  },
  "roles": []
}
Key Type Description
user.login String Login
user.firstname String First name
user.lastname String Last name
user.email String E-mail
user.active String Is active
user.insertDate Date Creation date, format: yyyy/MM/dd HH:mm:ss
user.updateDate Date Last update date, format: yyyy/MM/dd HH:mm:ss
roles Array List of user role

Create a user token

Create a user token

curl                                           \
  --header "Authorization: Basic BASE64_TOKEN" \
  --header "Content-Type: application/json"    \
  --request POST                               \
  --data 'DATA_TO_SEND'                        \
  http://spy:8080/octo-spy/api/users/token

Example of data to send:

TOKEN_NAME

Example of success:

{
  "token": "generated token value"
}

Body parameters: Token name.

Delete a user token

delete a user token

curl                                           \
  --header "Authorization: Basic BASE64_TOKEN" \
  --request DELETE                             \
  http://spy:8080/octo-spy/api/users/token/[name]

Get all token's names of a user

Get all token's names of a user

curl                                           \
  --header "Authorization: Basic BASE64_TOKEN" \
  --request GET                                \
  http://spy:8080/octo-spy/api/users/token

Example of success:

["token1", "token2"]

Future developments

New Features

And many more!

API refacto

Contribution

Octo community is growing incredibly fast and if you’re reading this, there’s a good chance you’re ready to join it. So… welcome!

To improve Octo's documentation make a pull request on this github repository.

To improve Octo's API make a pull request on this github repository.

To improve Octo's web application make a pull request on this github repository.