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:
- Database: postgresql version 13.3
- API: octo-spy made in Java
- Web application: octo-board made in Vue-js
Docker
Build
octo-spy
andocto-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:
- Development
- Integration
- Pre-production
- Production
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:
not_
: 'Not' operator for the search, which applies negation:fieldName=value
: Return all data that matchvalue
fieldName=not_value
: Return all data that different thanvalue
|
: 'Or' operator that makes a list:fieldName=value1|value2
: Return all data that matchvalue1
orvalue2
fieldName=not_value1|value2
: Return all data that different thanvalue1
or equals tovalue2
null
andnot_null
Text search
- Equals:
fieldName=value
- Like:
fieldName=lk_value
value
can contain*
to symbolise any characters. It can be escape:\*
- Not like:
fieldName=not_lk_value
- Multiple equals:
fieldName=value1|value2|value3
- Multiple like:
fieldName=lk_value1|lk_value2|lk_value3
- All combined:
fieldName=lk_value1|not_lk_value2|value3|not_value4
Date search
Input date format: yyyy-MM-dd HH:mm:ss
Ouput date format: yyyy/MM/dd HH:mm:ss
- Equals:
fieldName=2000-01-01 00:00:00
- Inferior:
fieldName=lt2000-01-01 00:00:00
- Superior:
fieldName=gt2000-01-01 00:00:00
- Between:
fieldName=2000-01-01 00:00:00bt2001-01-01 00:00:00
- All combined:
fieldName=2000-01-01 00:00:00|lt2000-01-01 00:00:00
Number search
- Equals:
fieldName=1
- Not equals:
fieldName=not_1
- All combined:
fieldName=1|2|not_3
Boolean search
- Equals:
fieldName=true
- Not equals:
fieldName=not_false
Authentication's errors
Apply for all endpoint that need authentication.
401 - Authentication error
: On bad authorization property401 - Authentication error
: On bad authentication scheme401 - Authentication has failed
: On authentication error
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
- Need to authentication: Yes
- Token allowed: No
- Path:
/octo-spy/api/administrator/password
- Method:
PUT
- Data type:
String
encoded in base64 - Success status:
204 - No content
- Errors status:
400 - Field value is empty
: On blank encoded password400 - Wrong field value
: Bad length on decoded password500 - Internal error occurred
: On no default admin account
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
- Need to authentication: Yes
- Token allowed: No
- Path:
/octo-spy/api/administrator/email
- Method:
PUT
- Data type:
String
- Success status:
204 - No content
- Errors status:
400 - Wrong field value
: On invalid e-mail500 - Internal error occurred
: On no default admin account
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."
}]
}
- Need to authentication: Yes
- Token allowed: No
- Path:
/octo-spy/api/alerts
- Method:
GET
- Success status:
200 - Ok
: On alerts204 - No content
: On no alerts
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:
- Having same default administrator password.
- Having same default adminstrator e-mail.
- Having a incompatible database version.
Client
Get all clients
Get all application clients
curl \
--request GET \
http://spy:8080/octo-spy/api/clients
Example of success:
["Client1", "Client2"]
- Need to authentication: No
- Path:
/octo-spy/api/clients
- Method:
GET
- Success status:
200 - Ok
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
}
- Need to authentication: No
- Path:
/octo-spy/api/deployments/[id]
- Method:
GET
- Query parameter:
id
: id of deployment
- Success status:
200 - Ok
- Errors status:
400 - Field value is empty
: On blank id404 - Entity not found
: On unknown id
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
}]
}
- Need to authentication: No
- Path:
/octo-spy/api/deployments
- Method:
GET
- Success status:
200 - Ok
: When all resources are returned206 - Partial content
: When partial resources are returned
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
}]
}
- Need to authentication: No
- Path:
/octo-spy/api/deployments/last
- Method:
GET
- Success status:
200 - Ok
: When all resources are returned206 - Partial content
: When partial resources are returned
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
}
- Need to authentication: Yes
- Token allowed: Yes
- Path:
/octo-spy/api/deployments
- Method:
POST
- Data type:
JSON
- Success status:
201 - Created
- Errors status:
400 - Field value is empty
: On blank environment, project, client or version404 - Entity not found
: On unknown environment or project
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
}
- Need to authentication: Yes
- Token allowed: Yes
- Path:
/octo-spy/api/deployments/[id]
- Method:
PATCH
- Query parameter:
id
: id of deployment
- Data type:
JSON
- Success status:
204 - No content
- Errors status:
400 - Field value is empty
: On blank environment, project, client or version404 - Entity not found
: On unknown environment or project
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",
}
- Need to authentication: Yes
- Token allowed: Yes
- Path:
/octo-spy/api/deployments/progress
- Method:
DELETE
- Data type:
JSON
- Success status:
204 - No content
- Errors status:
400 - Field value is empty
: On blank environment or project404 - Entity not found
: On unknown environment, project, deployment or deploymentProgress
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
}
]
- Need to authentication: No
- Path:
/octo-spy/api/clients
- Method:
GET
- Success status:
200 - Ok
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
}
- Need to authentication: Yes
- Token allowed: Yes
- Path:
/octo-spy/api/environments
- Method:
POST
- Data type:
JSON
- Success status:
201 - Created
- Errors status:
400 - Field value is empty
: On blank name400 - Wrong field value.
: On duplicate name
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
}
- Need to authentication: Yes
- Token allowed: Yes
- Path:
/octo-spy/api/environments/[id]
- Method:
PATCH
- Query parameter:
id
: id of environment
- Data type:
JSON
- Success status:
204 - No content
- Errors status:
400 - Field value is empty
: On blank name400 - Wrong field value.
: On duplicate name404 - Entity not found
: On unknown environment
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",
}
- Need to authentication: Yes
- Token allowed: Yes
- Path:
/octo-spy/api/environments
- Method:
DELETE
- Query parameter:
id
: id of environment
- Data type:
JSON
- Success status:
204 - No content
- Errors status:
404 - Entity not found
: On unknown id
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
}
- Need to authentication: No
- Path:
/octo-spy/api/info
- Method:
GET
- Success status:
200 - Ok
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
}
- Need to authentication: No
- Path:
/octo-spy/api/projects/[id]
- Method:
GET
- Query parameter:
id
: id of project
- Success status:
200 - Ok
- Errors status:
400 - Field value is empty
: On blank id404 - Entity not found
: On unknown id
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
}]
}
- Need to authentication: No
- Path:
/octo-spy/api/projects
- Method:
GET
- Success status:
200 - Ok
: When all resources are returned206 - Partial content
: When partial resources are returned
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"
}
- Need to authentication: Yes
- Token allowed: No
- Path:
/octo-spy/api/projects
- Method:
PATCH
- Data type:
JSON
- Success status:
204 - No content
- Errors status:
400 - Field value is empty
: On blank id404 - Entity not found
: On unknown id
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
}
- Need to authentication: Yes
- Token allowed: No
- Path:
/octo-spy/api/projects
- Method:
POST
- Data type:
JSON
- Success status:
201 - Created
- Errors status:
400 - Field value is empty
: On blank name404 - Entity not found
: On unknown master project name
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]
- Need to authentication: Yes
- Token allowed: No
- Path:
/octo-spy/api/projects/[id]
- Method:
DELETE
- Query parameter:
id
: id of project
- Success status:
204 - No content
- Errors status:
400 - Field value is empty
: On blank id404 - Entity not found
: On unknown 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
}]
- Need to authentication: No
- Path:
/octo-spy/api/report/deployments
- Method:
GET
- Success status:
200 - Ok
: When all resources are returned
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": []
}
- Need to authentication: Yes
- Token allowed: Yes
- Path:
/octo-spy/api/users/me
- Method:
GET
- Success status:
200 - Ok
Key | Type | Description |
---|---|---|
user.login | String | Login |
user.firstname | String | First name |
user.lastname | String | Last name |
user.email | String | |
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"
}
- Need to authentication: Yes
- Token allowed: No
- Path:
/octo-spy/api/users/token
- Method:
POST
- Data type:
JSON
- Success status:
201 - Created
- Errors status:
400 - Wrong field value
: On duplicate token name for an user
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]
- Need to authentication: Yes
- Token allowed: No
- Path:
/octo-spy/api/users/token/[name]
- Method:
DELETE
- Query parameter:
name
: token name
- Success status:
204 - No content
- Errors status:
400 - Field value is empty
: On blank name404 - Entity not found
: On unknown token for user
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"]
- Need to authentication: Yes
- Token allowed: No
- Path:
/octo-spy/api/users/token
- Method:
GET
- Success status:
200 - Ok
: When all resources are returned
Future developments
New Features
- LDAP authentication, imply this features:
- LDAP settings page
- Managing user (enable/disable and add new user)
- Managing user roles
- Notification center for user. Send mail on wanted deployment.
- Add explanation/schema on models
- Add "auto-refresh" fonctionnality
- Add information on project/deployment card like :
- Jira
- Sonar
- ssh
And many more!
API refacto
- Standardize all endpoint return
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.