MongoDB¶

Server-level MongoDB management when the plugin is enabled.

All endpoints below are mounted under /api. Authentication: Authorization: Bearer <token> unless noted as public.

Endpoint count: 11

Endpoints¶

Method	Path	Handler	Guards
`POST`	`/api/mongodb/backup`	`mongoDBBackup`	RequirePermission(db, "administrative_operations")
`GET`	`/api/mongodb/backups`	`mongoDBListBackups`	RequirePermission(db, "administrative_operations")
`DELETE`	`/api/mongodb/backups/:name`	`mongoDBDeleteBackup`	RequirePermission(db, "administrative_operations")
`POST`	`/api/mongodb/restart`	`mongoDBRestart`	RequirePermission(db, "administrative_operations")
`POST`	`/api/mongodb/restore`	`mongoDBRestore`	RequirePermission(db, "administrative_operations")
`POST`	`/api/mongodb/start`	`mongoDBStart`	RequirePermission(db, "administrative_operations")
`GET`	`/api/mongodb/status`	`getMongoDBStatus`	RequirePermission(db, "administrative_operations")
`POST`	`/api/mongodb/stop`	`mongoDBStop`	RequirePermission(db, "administrative_operations")
`GET`	`/api/mongodb/users`	`mongoDBListUsers`	RequirePermission(db, "administrative_operations")
`POST`	`/api/mongodb/users`	`mongoDBCreateUser`	RequirePermission(db, "administrative_operations")
`DELETE`	`/api/mongodb/users/:username`	`mongoDBDeleteUser`	RequirePermission(db, "administrative_operations")

Source¶

Handlers for this section live in api/routes/handlers_*.go in the StarkOne source. Each handler binds its request body with gin.ShouldBindJSON(&req) and responds with the standard envelope:

{ "data": { ... } }

On error:

{ "error": { "code": "string", "message": "string" } }

Reference¶

`POST /api/mongodb/backup`¶

Creates a full MongoDB dump (via mongodump) into a timestamped directory under /var/backups/mongodb.

Guards: RequirePermission(db, "administrative_operations")

Response - 200 OK

This handler returns a flat (non-enveloped) body containing the generated backup directory name.

{ "success": true, "backup": "mongo-backup-2026-06-17-153012" }

Errors

Status	Code	Meaning
`500`	`backup_error`	`mongodump` failed; the message includes the underlying error.

Side effects

Creates the directory /var/backups/mongodb (mode 0755) if it does not exist.
Runs mongodump --out /var/backups/mongodb/mongo-backup-<timestamp>, writing a full dump to disk.

Example

curl -X POST https://panel.example.com:2087/api/mongodb/backup \
  -H "Authorization: Bearer $TOKEN"

`GET /api/mongodb/backups`¶

Lists up to the 10 most recent MongoDB backup directories under /var/backups/mongodb, newest first.

Guards: RequirePermission(db, "administrative_operations")

Response - 200 OK

Each backup entry includes its directory name, last-modified timestamp, and human-readable total size. If the backup directory cannot be read, an empty list is returned (still 200).

{
  "data": {
    "backups": [
      { "name": "mongo-backup-2026-06-17-153012", "date": "2026-06-17 15:30", "size": "12.4 MB" }
    ]
  }
}

Example

curl https://panel.example.com:2087/api/mongodb/backups \
  -H "Authorization: Bearer $TOKEN"

`DELETE /api/mongodb/backups/:name`¶

Deletes a single backup directory by name from /var/backups/mongodb.

Guards: RequirePermission(db, "administrative_operations")

Path parameters

Name	Type	Description
`name`	string	Backup directory name (as returned by the list endpoint), e.g. `mongo-backup-2026-06-17-153012`.

Response - 200 OK

Flat (non-enveloped) body.

{ "success": true }

Errors

Status	Code	Meaning
`404`	`not_found`	No backup directory with that name exists.
`500`	`delete_error`	Removal failed; the message includes the underlying error.

Side effects

Recursively removes /var/backups/mongodb/<name> (os.RemoveAll).

Example

curl -X DELETE https://panel.example.com:2087/api/mongodb/backups/mongo-backup-2026-06-17-153012 \
  -H "Authorization: Bearer $TOKEN"

`POST /api/mongodb/restart`¶

Restarts the mongod systemd service.

Guards: RequirePermission(db, "administrative_operations")

Response - 200 OK

Flat (non-enveloped) body.

{ "success": true, "message": "MongoDB restarted" }

Errors

Status	Code	Meaning
`500`	`restart_error`	`systemctl restart mongod` failed.

Side effects

Runs systemctl restart mongod.

Example

curl -X POST https://panel.example.com:2087/api/mongodb/restart \
  -H "Authorization: Bearer $TOKEN"

`POST /api/mongodb/restore`¶

Restores a previously created backup directory with mongorestore --drop (existing collections are dropped before restore).

Guards: RequirePermission(db, "administrative_operations")

Request body

{ "backup": "string (required)" }

Field	Type	Required	Description
`backup`	string	yes	Backup directory name under `/var/backups/mongodb` to restore from.

Response - 200 OK

Flat (non-enveloped) body.

{ "success": true, "message": "Restore completed" }

Errors

Status	Code	Meaning
`400`	`bad_request`	Body failed binding (e.g. missing `backup`).
`404`	`not_found`	The named backup directory does not exist.
`500`	`restore_error`	`mongorestore` failed; the message includes the underlying error.

Side effects

Runs mongorestore --drop /var/backups/mongodb/<backup>, dropping and replacing existing collections.

Example

curl -X POST https://panel.example.com:2087/api/mongodb/restore \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"backup": "mongo-backup-2026-06-17-153012"}'

`POST /api/mongodb/start`¶

Starts the mongod systemd service.

Guards: RequirePermission(db, "administrative_operations")

Response - 200 OK

Flat (non-enveloped) body.

{ "success": true, "message": "MongoDB started" }

Errors

Status	Code	Meaning
`500`	`start_error`	`systemctl start mongod` failed.

Side effects

Runs systemctl start mongod.

Example

curl -X POST https://panel.example.com:2087/api/mongodb/start \
  -H "Authorization: Bearer $TOKEN"

`GET /api/mongodb/status`¶

Reports MongoDB service status, version, uptime, connection count, resident memory, and data-directory size.

Guards: RequirePermission(db, "administrative_operations")

Response - 200 OK

Fields are best-effort: if the shell stats query or version probe fails, the corresponding fields fall back to their zero/empty defaults. version is parsed from mongod --version; uptime/connections/memory_mb come from db.serverStatus() (memory falls back to systemctl show mongod); data_size is from du -sh of the data directory.

{
  "data": {
    "running": true,
    "version": "7.0.5",
    "uptime": "12h 4m",
    "connections": 7,
    "memory_mb": 256,
    "data_size": "1.2G"
  }
}

Side effects

Read-only probes: systemctl is-active mongod, mongod --version, a mongosh/mongo serverStatus() eval, systemctl show mongod, and du -sh on /var/lib/mongo or /var/lib/mongodb.

Example

curl https://panel.example.com:2087/api/mongodb/status \
  -H "Authorization: Bearer $TOKEN"

`POST /api/mongodb/stop`¶

Stops the mongod systemd service.

Guards: RequirePermission(db, "administrative_operations")

Response - 200 OK

Flat (non-enveloped) body.

{ "success": true, "message": "MongoDB stopped" }

Errors

Status	Code	Meaning
`500`	`stop_error`	`systemctl stop mongod` failed.

Side effects

Runs systemctl stop mongod.

Example

curl -X POST https://panel.example.com:2087/api/mongodb/stop \
  -H "Authorization: Bearer $TOKEN"

`GET /api/mongodb/users`¶

Lists MongoDB users by querying db.system.users in the admin database via the shell.

Guards: RequirePermission(db, "administrative_operations")

Response - 200 OK

Each user includes its name, defining database, and a list of role@db strings. If the shell command fails, an empty list is returned (still 200).

{
  "data": {
    "users": [
      { "user": "user1", "db": "admin", "roles": ["readWrite@appdb"] }
    ]
  }
}

Side effects

Read-only: runs a mongosh/mongo eval against the admin database.

Example

curl https://panel.example.com:2087/api/mongodb/users \
  -H "Authorization: Bearer $TOKEN"

`POST /api/mongodb/users`¶

Creates a MongoDB user in the specified database with a single role (defaults to readWrite).

Guards: RequirePermission(db, "administrative_operations")

Request body

{
  "username": "string (required)",
  "password": "string (required)",
  "database": "string (required)",
  "role": "string (optional)"
}

Field	Type	Required	Description
`username`	string	yes	Name of the user to create.
`password`	string	yes	Password for the new user.
`database`	string	yes	Database the user is created on; also the database the role is granted on.
`role`	string	no	Role to grant on `database`. Defaults to `readWrite` when empty.

Response - 200 OK

Flat (non-enveloped) body.

{ "success": true }

Errors

Status	Code	Meaning
`400`	`bad_request`	Body failed binding (missing `username`, `password`, or `database`).
`500`	`create_error`	The shell `createUser` command failed; the message contains its combined output.

Side effects

Runs a mongosh/mongo eval invoking db.getSiblingDB(<database>).createUser(...), persisting a new user.

Example

curl -X POST https://panel.example.com:2087/api/mongodb/users \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username": "user1", "password": "secret", "database": "appdb", "role": "readWrite"}'

`DELETE /api/mongodb/users/:username`¶

Drops a MongoDB user from a database (defaults to admin).

Guards: RequirePermission(db, "administrative_operations")

Path parameters

Name	Type	Description
`username`	string	Name of the user to drop.

Query parameters

Name	Type	Optional	Description
`db`	string	yes	Database to drop the user from. Defaults to `admin` when omitted.

Response - 200 OK

Flat (non-enveloped) body.

{ "success": true }

Errors

Status	Code	Meaning
`500`	`delete_error`	The shell `dropUser` command failed; the message contains its combined output.

Side effects

Runs a mongosh/mongo eval invoking db.dropUser(<username>) against the selected database, removing the user.

Example

curl -X DELETE "https://panel.example.com:2087/api/mongodb/users/user1?db=appdb" \
  -H "Authorization: Bearer $TOKEN"

MongoDB¶

Endpoints¶

Source¶

Reference¶

POST /api/mongodb/backup¶

GET /api/mongodb/backups¶

DELETE /api/mongodb/backups/:name¶

POST /api/mongodb/restart¶

POST /api/mongodb/restore¶

POST /api/mongodb/start¶

GET /api/mongodb/status¶

POST /api/mongodb/stop¶

GET /api/mongodb/users¶

POST /api/mongodb/users¶

DELETE /api/mongodb/users/:username¶

`POST /api/mongodb/backup`¶

`GET /api/mongodb/backups`¶

`DELETE /api/mongodb/backups/:name`¶

`POST /api/mongodb/restart`¶

`POST /api/mongodb/restore`¶

`POST /api/mongodb/start`¶

`GET /api/mongodb/status`¶

`POST /api/mongodb/stop`¶

`GET /api/mongodb/users`¶

`POST /api/mongodb/users`¶

`DELETE /api/mongodb/users/:username`¶