Servers Configurations API

General notes

This endpoint is used for specifying server configurations.

Embeddable fields

Name	Type	Description
`server`	Server	Related Server.
`project`	Project	Related Project.
`server_cleaners`	ServerCleaners[]	Collection of related ServerCleaners.
`server_aliases`	ServerAliases[]	Collection of related ServerAliases.
`server_queue_types`	ServerQueueType[]	Collection of related ServerQueueTypes.

Content

Server Configurations collection:

[GET] index
[POST] create server configuration

Single Server Configuration:

[GET] show
[PATCH] update server configuration
[DELETE] delete server configuration

Server Configurations public collection:

[GET] Public collection

Server Configurations Collection

Get List of Server Configurations

GET /api/v0/server-configurations

This method needs permission read on servers-configurations.

Method for listing all Server Configurations.

Request

Index behaviour	Definition
Paginated by default	No
Sorting	`id`, `domain`, `project_id`, `server_id`, `engine`, `php_version`, `public_dir`, `scheduler_running`, `queue_engine`, `queue_running`, `queue_processes`, `password_protected`, `encrypted_credential`, `is_removed`, `created_at`, `updated_at`
Filters	`id`:enum, `domain`:string, `project_id`:int, `server_id`:int, `engine`:string, `php_version`:string, `public_dir`:string, `scheduler_running`:bool, `queue_engine`:string, `queue_running`:bool, `queue_processes`:int, `password_protected`:bool, `encrypted_credential`:string, `is_removed`:bool, `created_at`, `updated_at`

GET /api/v0/server-configurations?embed=server_cleaners,server_aliases,server_queue_types HTTP/1.1
Content-Type: application/json

Responses

200 OK

GET /api/v0/server-configurations HTTP/1.1
Content-Type: application/json
Status-Code: 200
{
    "items": [
        {
            "id": 1,
            "name": "Dev",
            "domain": "docker.simplo.cz",
            "project_id": 1,
            "server_id": 1,
            "engine": "php",
            "php_version": "8.1",
            "public_dir": "/public",
            "scheduler_enabled": true,
            "queue_enabled": true,
            "queue_engine": "worker",
            "queue_processes": 3,
            "password_protected": true,
            "username": "pech",
            "is_removed": false,
            "created_at": "2023-10-09T08:32:23.000000Z",
            "updated_at": "2023-10-09T08:32:23.000000Z",
            "_links": [
                {
                    "href": "/api/v0/server-configurations/1",
                    "rel": "self",
                    "type": "GET"
                }
            ],
            "_embedded": {
                "server": {
                    "id": 1,
                    "name": "gateway01.simplo.cz",
                    "hetzner_server_id": 26776140,
                    "ipv4": "11.22.33.44",
                    "ipv6": "aaaa:bbbb:cccc:dddd::/64",
                    "private_net_ip": "11.2.3.4",
                    "is_gateway": true,
                    "created_at": "2023-10-09T10:30:05+0200",
                    "updated_at": "2023-10-09T10:30:05+0200"
                },
                "project": {
                    "id": 1,
                    "name": "PROJ_A",
                    "goodday_id": null,
                    "parent_id": null,
                    "client_id": null,
                    "status_id": 2,
                    "status_comment": null,
                    "responsible_user_id": null,
                    "active": true,
                    "description": null,
                    "start_date": null,
                    "end_date": null,
                    "priority": null,
                    "progress": null,
                    "type": null,
                    "is_client": true,
                    "google_drive_url": null,
                    "billable": true,
                    "billing_type": null,
                    "billing_time_type": null,
                    "price": 0,
                    "estimated_price": 0,
                    "goodday_created_at": null,
                    "created_at": "2023-10-28T10:29:04+0200",
                    "updated_at": "2023-10-28T10:29:04+0200"
                },
                "server_cleaners": [
                    {
                        "id": 1,
                        "name": "public_logs_cleaner",
                        "relative_path": "/storage/logs",
                        "remove_after_days": 10,
                        "selectors": [
                            "laravel-*.log",
                            "*.php"
                        ],
                        "server_configuration_id": 1,
                        "remove_empty_directories": false,
                        "created_at": "2023-10-09T10:32:23+0200",
                        "updated_at": "2023-10-09T10:32:23+0200"
                    },
                    {
                        "id": 2,
                        "name": "local_logs_cleaner",
                        "relative_path": "/local/logs",
                        "remove_after_days": 2,
                        "selectors": [
                          "laravel-*.log"
                        ],
                        "server_configuration_id": 1,
                        "created_at": "2023-10-09T10:32:23+0200",
                        "updated_at": "2023-10-09T10:32:23+0200"
                    }
                ],
                "server_aliases": [
                    {
                        "id": 1,
                        "name": "dev.docker.sdev.cz",
                        "created_at": "2023-10-09T10:32:23+0200",
                        "updated_at": "2023-10-09T10:32:23+0200"
                    },
                    {
                        "id": 2,
                        "name": "test.docker.sdev.cz",
                        "created_at": "2023-10-09T10:32:23+0200",
                        "updated_at": "2023-10-09T10:32:23+0200"
                    }
                ],
                "server_queue_types": [
                    {
                        "id": 6,
                        "name": "io",
                        "processes": 5,
                        "server_configuration_id": 18,
                        "created_at": "2024-01-22T13:54:55+0100",
                        "updated_at": "2024-01-22T13:54:55+0100"
                    }
                ],
            }
        },
    ]
}

Create Server Configuration

POST /api/v0/server-configurations

This method requires create on server-configurations.

Method for creating new Server Configurations.

Request

Param	Type	Description	Requirements
`name`	string	Name	Required. Must be a string.
`domain`	string	Domain	Required. Must be a string.
`server_id`	int	Server identifier	Required. Must be int with reference to Server table.
`project_id`	int	Project identifier	Required. Must be int with reference to Project table.
`engine`	string	Engine type	Required. Must be one of following strings - php, static.
`php_version`	string	PHP version	Required. Must be a string matching following pattern /[0-9]{1,2}.[0-9]/.
`scheduler_enabled`	bool	Scheduler state	Required. Must be a bool.
`queue_enabled`	bool	Queue state	Required. Must be a bool.
`queue_engine`	string	Queue engine type	Required if queue is enabled. Must be one of following strings - worker, horizon.
`queue_processes`	int	Amount of queue processes	Required if queue is enabled. Must be integer.
`password_protected`	bool	Password protection	Required. Must be bool.
`login`	string	Login	Required if password_protected is true.
`password`	string	Password	Required if password_protected is true.
`cleaners`	array[]	Array of ServerCleaners.	Must be array of ServerCleaners.
`aliases`	array[]	Array of ServerAliases.	Must be array of ServerAliases.
`queue_types`	array[]	Array of Queue Types.	Must be array of QueueTypes.

POST /api/v0/server-configurations HTTP/1.1
Content-Type: application/json

{
    "name": "Dev",
    "domain": "docker.simplo.cz",
    "server_id": 7,
    "project_id": 1,
    "engine": "php",
    "php_version": "8.1",
    "scheduler_enabled": true,
    "queue_enabled": true,
    "queue_engine": "worker",
    "queue_processes": 3,
    "password_protected": true,
    "public_dir": "/public",
    "login": "pech",
    "password": "abc123",
    "cleaners": [
        {queue_ena
            "name": "public_logs_cleaner",
            "relative_path": "/storage/logs",
            "selectors": "laravel-*.log, *.php",
            "remove_after_days": 10,
            "remove_empty_directories": true,
        },
        {
            "name": "local_logs_cleaner",
            "relative_path": "/local/logs",
            "selectors": "laravel-*.log"
            "remove_after_days": 2
        }
    ],
    "aliases": [
        "dev.docker.sdev.cz",
        "pech.docker.sdev.cz"
    ],
    "queue_types": [
        {
            "name": "io"
        }
    ]
}

Responses

201 CREATED

Successfully created.

422 UNPROCESSABLE ENTITY

Validation error.

Single user

Show Server Configuration

GET /api/v0/server-configurations/{serverConfigurationId}

Request

This method requires read on server-configurations.
Responses

204 NO CONTENT

Successfully deleted.

404 NOT FOUND

Server Configuration with that id was not found.

Update Server Configuration

PATCH /api/v0/server-configurations/{serverConfigurationId}

This method requires update on server-configurations.

Method for editing Server Configuration.

Request

Request is similar to POST request. No fields are required. All exceptions are mentioned below.

Updating cleaners, queue types and aliases does only take into consideration the new ones (deleting the old ones). If you wish to keep both old and new ones, please provide them all with patch request.

Example:

currently set:

...
"cleaners": [
      {
          "name": "foo",
          "relative_path": "/storage/logs",
          "selectors": "laravel-*.log, *.php",
          "remove_after_days": 10
      }
]

want to add:

{
  "name": "local_logs_cleaner",
  "relative_path": "/local/logs",
  "selectors": "laravel-*.log",
  "remove_after_days": 2
} 

PATCH /api/v0/server-configurations/1

...
"cleaners": [
    {
        "name": "public_logs_cleaner",
        "relative_path": "/storage/logs",
        "selectors": "laravel-*.log, *.php",
        "remove_after_days": 10
    },
    {
        "name": "local_logs_cleaner",
        "relative_path": "/local/logs",
        "selectors": "laravel-*.log",
        "remove_after_days": 2
    } 
]

Updating password requires providing parameter old_password. This parameter must match currently store password.
- Example:
```
PATCH /api/v0/server-configurations/1
...
"old_password": "oldPass123",
"password": "newPass123"
```
Changing parameter password_protected from false to true will result in requirement of fields login & password.

Responses

200 OK

Updated.

404 NOT FOUND

Server Configuration with this ID does not exist.

Delete Server Configuration

DELETE /api/v0/server-configurations/{serverConfigurationId}

This method requires delete on server-configurations.

This method performs soft delete. This means, that deleted files are not removed immediately, but after some period of time.

Request

DELETE /api/v0/server-configurations/1 HTTP/1.1

Responses

204 NO CONTENT

Successfully deleted.

404 NOT FOUND

Server Configuration with that id was not found.

Server Configurations public collection

Get public collection

GET /api/v0/public-server-configurations

This endpoint has information about servers and its configurations. Endpoint is protected with shared secret and only requests with IP address from accepted pool will be accepted.
Request
GET /api/v0/public-server-configurations?secret=password HTTP/1.1

Response

{
    "gateway": {
        "fqdn": "gateway01.simplo.cz"
    },
    "projects": {
        "PROJ_B": {
            "apps": {
                "docker01": {
                    "engine": "php",
                    "version": "8.1",
                    "domain": "docker01.simplo.cz",
                    "aliases": [
                        "dev.docker.sdev.cz",
                        "pech.docker.sdev.cz"
                    ],
                    "publicDir": "/public",
                    "security": {
                        "enabled": true,
                        "username": "pech",
                        "password": "$2y$10dksaF18c5bvc6..."
                    },
                    "is_removed": true
                },
                "puppetmaster": {
                    "engine": "php",
                    "version": "8.1",
                    "domain": "puppetmaster.simplo.cz",
                    "publicDir": "/public",
                    "security": {
                        "enabled": false,
                        "username": null,
                        "password": null
                    },
                    "is_removed": false,
                    "scheduler": {
                        "enable": true
                    },
                    "queue": {
                        "enable": true,
                        "engine": "worker",
                        "processes": 12,
                        "types": {
                            "io": {
                                "processes": null
                            }
                        }
                    },
                    "cleanups": {
                        "/dir": {
                            "matches": [
                                "abc",
                                "def"
                            ],
                            "remove_after_days": 3,
                            "rmdirs": true
                        }
                    },
                    "aliases": [
                        "dev.docker.sdev.cz",
                        "pech.docker.sdev.cz"
                    ]
                }
            }
        }
    }
}

Notes

Get notes for server configuration

Request

GET /api/v0/server-configurations/1/notes HTTP/1.1

Response

200 Ok

{
    "items": [
        {
            "id": 1,
            "noteable_type": "App\\Containers\\ServerConfigurations\\ServerConfigurations\\Models\\ServerConfiguration",
            "noteable_id": 1,
            "text": "Ahoj",
            "user_id": 2,
            "created_at": "2024-01-15T13:04:12+0100",
            "updated_at": "2024-01-15T13:04:12+0100",
            "_links": [
                {
                    "href": "/api/v0/notes/1",
                    "rel": "self",
                    "type": "GET"
                }
            ]
        }
    ],
    "_meta": {
        "page": 1,
        "total_pages": 1,
        "records": 1,
        "per_page": 100
    }
}

Add notes for server configuration

Request

POST /api/v0/server-configurations/1/notes HTTP/1.1

General notes​

Embeddable fields​

Content​

Server Configurations Collection

Get List of Server Configurations​

GET /api/v0/server-configurations

Request​

Responses​

200 OK​

Create Server Configuration​

POST /api/v0/server-configurations

Request​

Responses​

201 CREATED​

422 UNPROCESSABLE ENTITY​

Single user

Show Server Configuration​

GET /api/v0/server-configurations/{serverConfigurationId}

Request​

Responses​

204 NO CONTENT​

404 NOT FOUND​

Update Server Configuration​

PATCH /api/v0/server-configurations/{serverConfigurationId}

Request​

Responses​

200 OK​

404 NOT FOUND​

Delete Server Configuration​

DELETE /api/v0/server-configurations/{serverConfigurationId}

Request​

Responses​

204 NO CONTENT​

404 NOT FOUND​

Server Configurations public collection

Get public collection​

GET /api/v0/public-server-configurations

Request​

Response​

Notes

Get notes for server configuration​

Request​

Response​

200 Ok​

Add notes for server configuration​

Request​

Response​

200 OK​

General notes

Embeddable fields

Content

Get List of Server Configurations

Request

Responses

200 OK

Create Server Configuration

Request

Responses

201 CREATED

422 UNPROCESSABLE ENTITY

Show Server Configuration

Request

Responses

204 NO CONTENT

404 NOT FOUND

Update Server Configuration

Request

Responses

200 OK

404 NOT FOUND

Delete Server Configuration

Request

Responses

204 NO CONTENT

404 NOT FOUND

Get public collection

Request

Response

Get notes for server configuration

Request

Response

200 Ok

Add notes for server configuration

Request

Response

200 OK