Backup & Job Status API — Laravel Integration
How to implement database backup and live job status in ems-frontend: two Laravel
routes that talk to the db-backup API, and the browser code that drives them.
This is the integration how-to. For operating and troubleshooting the backup stack
itself — reading the live log, the layout of /opt/backup, restoring, the byte
progress fields — see Database Backup — Laravel EMS Frontend.
What you are building
Two calls, and the difference between them is the whole design:
- a trigger that starts a job and returns immediately
- a status call that reports on the job while it runs
The trigger used to be the backup — it held the HTTP request open for the whole dump. A full backup is 16 databases and takes about an hour, so that request was capped at 600 s and died around database 3 of 16 every time, taking the dump with it. The trigger now returns as soon as the job is queued, and the browser polls.
sequenceDiagram
participant B as Browser
participant F as ems-frontend (Laravel)
participant D as db-backup:8096
B->>F: POST /api/v1/ems/trigger-backup
F->>D: POST /api/v1/backup
D-->>F: 202 {"status":"accepted"}
F-->>B: 200 {"message":"...","response":{...}}
loop every 3 s, while running is true
B->>F: GET /api/v1/ems/backup-status?u_key=...
F->>D: GET /api/v1/job/status
D-->>F: 200 {"running":true,"progress":{...}}
F-->>B: 200 {"message":"...","response":{...}}
end
Neither Laravel hop blocks for the length of the backup. triggerBackup() and
backupStatus() are both short requests, so a plain PHP-FPM worker is never tied
up for an hour.
The contract on db-backup
Everything below is what the Laravel routes proxy. Base URL is
config('ems.backup_api_url'), normally http://db-backup:8096.
| Method | Path | Purpose | Returns |
|---|---|---|---|
POST |
/api/v1/backup |
Start a backup | 202 accepted, or 409 if busy |
POST |
/api/v1/restore |
Start a restore | 202 accepted, or 409 if busy |
GET |
/api/v1/job/status |
Snapshot of the current/last job | 200 JSON |
GET |
/api/v1/job/status?format=text |
The same as one line | 200 text/plain |
GET |
/api/v1/job/log?lines=N |
Tail of the job log | 200 text/plain |
GET |
/api/v1/health |
Service + backup mount health | 200 JSON |
POST /api/v1/backup
{ "type": "all", "db_name": "" }
type is all (databases then folders), db, or files. The response is the
acknowledgement, not the result:
{
"status": "accepted",
"operation": "backup",
"type": "all",
"message": "backup started in the background.",
"timestamp": "2026-10-02 10:41:07",
"status_url": "/api/v1/job/status",
"log_url": "/api/v1/job/log",
"db_name": ""
}
There is no
stdout,exit_codeorlog_filein this response. It used to carry the finished run's output because it waited for the job. Read the output fromGET /api/v1/job/loginstead.
POST /api/v1/restore
{ "type": "all", "timestamp": "", "target_dir": "" }
Same 202 shape. timestamp selects a snapshot (empty means latest);
target_dir is the restore destination when the script is asked to extract
elsewhere.
GET /api/v1/job/status
{
"status": "ok",
"running": true,
"operation": "backup",
"type": "db",
"pid": 9096,
"started_at": "2026-10-02 09:54:48",
"finished_at": null,
"elapsed_seconds": 372.1,
"elapsed_human": "6m12s",
"exit_code": null,
"log_file": "/tmp/gess-backup-jobs/backup-20261002-095448.log",
"progress": {
"phase": "databases",
"databases_done": 1,
"databases_started": 2,
"databases_total": 16,
"current_database": "ems_db",
"current_file": "/opt/backup/database/ems_db/ems_db_2026-10-02_09-54-54.sql.tmp",
"bytes_written": 7307282261,
"bytes_written_human": "6.81 GB",
"write_rate_bytes_per_s": 12897484.0,
"write_rate_human": "12.30 MB/s",
"file_age_seconds": 1.2,
"eta_seconds": 1120.4,
"eta_human": "18m40s"
},
"log_tail": ["[INFO] 2026-10-02 09:54:54 Backing up database: ems_db..."]
}
The keys worth binding to a UI:
| Key | Meaning |
|---|---|
running |
true while a job is in flight — the loop condition |
operation |
backup or restore |
type |
the --type that was requested |
elapsed_human |
6m12s, ticking while it runs |
exit_code |
null while running, 0 on success, 124 if it was stopped for stalled |
started_at / finished_at |
distinguishes "finished" from "never ran" |
progress.phase |
starting → databases → folders → finished |
progress.databases_done / databases_total |
the step counter, 1 / 16 |
progress.current_database |
what is being dumped right now |
progress.bytes_written_human |
6.81 GB — size of the live .tmp file |
progress.write_rate_human |
12.30 MB/s, averaged across polls |
progress.eta_human |
18m40s, or null early in a run |
progress.file_age_seconds |
large value means the dump has stalled |
Two traps in that payload:
progressis absent for a restore whose log has no database lines yet, andeta_*isnulluntil at least two databases have started. Always reach for the keys defensively.eta_secondsaverages the databases already finished in this run. Database sizes are uneven —ems_dbalone is ~10 GB of a ~30 GB backup — so treat it as an order of magnitude, not a promise.
The live numbers behind bytes_written come from the .tmp file the dump is
streaming into, since the script prints its target path only once at the start.
Database Backup explains why.
GET /api/v1/job/log?lines=N
The script's own output, line by line, capped at 5000 lines. Useful for a
"details" pane. Note that during a dump this log says very little — that is the
whole reason progress exists.
Step 1 — Configuration
config/ems.php:
'backup_api_url' => env('BACKUP_API_INTERNAL_URL', 'http://db-backup:8096'),
'backup_api_token' => env('BACKUP_ALERT_API_TOKEN'),
.env in ems-frontend:
BACKUP_API_INTERNAL_URL=http://db-backup:8096
db-backup enforces a bearer token only when BACKUP_API_TOKEN is set in its
own gess-stack.conf; it is empty by default, so the calls below send no
credentials and that is correct. If you ever set it, add the header to every
outbound call:
->withToken(config('ems.backup_api_token'))
Step 2 — Routes
Add all four to the existing EMS group in routes/api.php:139, behind the
hardware bearer middleware:
Route::group([
'prefix' => 'v1/ems',
'middleware' => ['verify.emsHardware_bearer'],
], function () {
// Health & Backups
Route::get('/backup-health', 'Api\V1\EMS\EMSOutBoundDataController@checkBackupHealth');
Route::get('/backup-status', 'Api\V1\EMS\EMSOutBoundDataController@backupStatus');
Route::post('/trigger-backup', 'Api\V1\EMS\EMSOutBoundDataController@triggerBackup');
Route::post('/trigger-restore', 'Api\V1\EMS\EMSOutBoundDataController@triggerRestore');
});
Because they sit behind verify.emsHardware_bearer, every call needs
Authorization: Bearer <ems-token> — the token in server_bearer_tokens where
status_01 = 'EMS'.
Then rebuild the route cache, or the new routes 404 even though they exist on disk:
docker exec -u www-data ems-frontend php artisan route:cache
Step 3 — The controller
All four live in
App\Http\Controllers\Api\V1\EMS\EMSOutBoundDataController. They share a shape:
validate u_key, resolve the user, call db-backup, and log the operation. The
polls deliberately skip UserOperationService — a request every 3 s would flood
the audit table.
Starting a backup
public function triggerBackup(Request $request)
{
try {
$validated = $request->validate([
'type' => 'nullable|string|in:all,db,files',
'db_name' => 'nullable|string|max:255',
'u_key' => 'required|string|max:20',
]);
$user = \App\Models\User::where('unic_key', $validated['u_key'])->first();
if (!$user) {
return response()->json(['message' => 'User unauthenticated.'], 401);
}
$type = $validated['type'] ?? 'all';
$dbName = $validated['db_name'] ?? '';
$url = rtrim(config('ems.backup_api_url'), '/') . '/api/v1/backup';
// 30 s, not 300: this call no longer waits for the backup. The job runs
// in the background on db-backup and answers 202 straight away.
$response = Http::timeout(30)
->acceptJson()
->post($url, ['type' => $type, 'db_name' => $dbName]);
UserOperationService::log(
'Trigger Backup', 'EMS Outbound', 'Trigger Backup',
'Triggered backup, type: ' . $type,
['type' => $type, 'db_name' => $dbName, 'status' => $response->status()]
);
if ($response->successful()) { // 202 is successful()
return response()->json([
'message' => 'Backup triggered successfully.',
'response' => $response->json(),
], 200);
}
if ($response->status() === 409) {
return response()->json([
'message' => 'A backup, restore or restart is already running.',
'response' => $response->json(),
], 409);
}
return response()->json([
'message' => 'Backup API returned an error.',
'response' => $response->json(),
], 500);
} catch (\Illuminate\Validation\ValidationException $e) {
return response()->json([
'message' => 'Invalid request parameters.',
'errors' => $e->errors(),
], 422);
} catch (\Exception $e) {
return response()->json([
'message' => 'Unable to connect to Backup API.',
'error' => $e->getMessage(),
], 500);
}
}
$response->successful() covers 200–299, so 202 passes without a change —
but surfacing 409 separately is worth it, because "something is already running"
is a normal condition, not an error the user should read as a failure.
Reading job status
public function backupStatus(Request $request)
{
try {
$validated = $request->validate([
'u_key' => 'required|string|max:20',
]);
$user = \App\Models\User::where('unic_key', $validated['u_key'])->first();
if (!$user) {
return response()->json(['message' => 'User unauthenticated.'], 401);
}
$url = rtrim(config('ems.backup_api_url'), '/') . '/api/v1/job/status';
// Short timeout: this is a poll, the caller just retries.
$response = Http::timeout(10)->acceptJson()->get($url);
if ($response->successful()) {
return response()->json([
'message' => 'Backup job status retrieved.',
'response' => $response->json(),
], 200);
}
return response()->json([
'message' => 'Backup API job status failed.',
'response' => $response->json(),
], 500);
} catch (\Exception $e) {
return response()->json([
'message' => 'Unable to connect to Backup API.',
'error' => $e->getMessage(),
], 500);
}
}
No UserOperationService::log() here on purpose.
Health before you start
$url = rtrim(config('ems.backup_api_url'), '/') . '/api/v1/health';
$response = Http::timeout(20)->acceptJson()->get($url);
Use it to refuse a backup when the storage is not mounted:
{
"status": "ok",
"service": "gess-backup-api",
"concurrency": { "server_class": "ThreadingHTTPServer", "threaded": true },
"backup_storage": { "mount_point": "/opt/backup", "is_mounted": true, "device": "/dev/sdb" }
}
Starting a restore
Identical to triggerBackup with /api/v1/restore and the extra fields, and the
same short timeout:
$validated = $request->validate([
'type' => 'nullable|string|in:all,db,files',
'timestamp' => 'nullable|string|max:32',
'target_dir' => 'nullable|string|max:255',
'u_key' => 'required|string|max:20',
]);
$response = Http::timeout(30)->acceptJson()->post(
rtrim(config('ems.backup_api_url'), '/') . '/api/v1/restore',
[
'type' => $validated['type'] ?? 'all',
'timestamp' => $validated['timestamp'] ?? '',
'target_dir' => $validated['target_dir'] ?? '',
]
);
Step 4 — Poll from the browser
Fire the trigger, then poll until running goes false:
async function runBackup({ type = 'db', uKey, token, onProgress }) {
const auth = { Authorization: `Bearer ${token}`, Accept: 'application/json' };
const res = await fetch('/api/v1/ems/trigger-backup', {
method: 'POST',
headers: { ...auth, 'Content-Type': 'application/json' },
body: JSON.stringify({ type, u_key: uKey }),
});
const triggered = await res.json();
if (res.status === 409) throw new Error(triggered.message);
if (!res.ok) throw new Error(triggered.message ?? `trigger failed (${res.status})`);
// 202 already came back; the job is queued. Follow it.
for (;;) {
const r = await fetch(
`/api/v1/ems/backup-status?u_key=${encodeURIComponent(uKey)}`,
{ headers: auth },
);
if (!r.ok) throw new Error(`status failed (${r.status})`);
const job = (await r.json()).response;
onProgress(job);
if (!job.running) return job;
await new Promise((done) => setTimeout(done, 3000));
}
}
Three seconds is a reasonable interval: the backend status call costs about a millisecond, and a faster poll buys nothing because the dumps are minutes long.
Step 5 — Render the progress
function render(job) {
const p = job.progress ?? {};
const done = p.databases_done ?? 0;
const total = p.databases_total ?? 0;
bar.style.width = total ? `${Math.round((done / total) * 100)}%` : '0%';
if (job.running) {
const rate = p.write_rate_human ? ` @ ${p.write_rate_human}` : '';
const eta = p.eta_human ? ` — ETA ~${p.eta_human}` : '';
label.textContent =
`${done}/${total} ${p.current_database ?? ''} ${p.bytes_written_human ?? ''}${rate}${eta}`;
return;
}
if (job.exit_code === 0) {
label.textContent = `Backup finished in ${job.elapsed_human}.`;
} else if (job.exit_code != null) {
label.textContent = `Backup failed (exit ${job.exit_code}) after ${job.elapsed_human}.`;
} else {
label.textContent = 'No backup has run since the backup API started.';
}
}
Knowing when the job is done
running is the only loop condition you need, but on its own it cannot tell
"finished" from "never started" — both are running: false. Use started_at:
running |
started_at |
Meaning |
|---|---|---|
true |
set | In flight, render the progress |
false |
set | The job ended — check exit_code for the result |
false |
null |
Nothing has run since db-backup started |
An exit_code of 124 is specific: the job was stopped because it stopped
writing anything at all, not because it ran too long. A backup that keeps making
progress is never interrupted, however long it takes — see BACKUP_JOB_TIMEOUT in
the companion page.
The job state lives in memory inside db-backup, so a container restart clears
it: the status endpoint goes back to running: false, started_at: null. It is a
progress view, not an audit trail — the durable evidence is the backup files.
Overlapping requests
Backup, restore and restart are serialized on purpose, so a second one gets 409
while a job runs:
{ "status": "error", "error": "Another backup, restore or restart is already running." }
Surface that plainly rather than as a failure. Disable the trigger button while
running is true and let the poll re-enable it — that avoids most 409s before
they happen.
Errors
| Symptom | Cause | What to do |
|---|---|---|
401 {"message":"User unauthenticated."} |
Unknown u_key |
Pass a real users.unic_key |
401 from the middleware |
Missing or wrong EMS bearer token | Send the token from server_bearer_tokens |
409 |
Something else is mutating | Wait for it; the lock releases when the job ends |
422 with errors |
type not one of all,db,files, or missing u_key |
Fix the payload |
500 "Unable to connect to Backup API." |
db-backup unreachable |
Check BACKUP_API_INTERNAL_URL resolves to http://db-backup:8096 |
500 "Backup API returned an error." |
db-backup answered non-2xx |
Read response — often the script was not mounted |
Trigger returns 200 with stdout in response |
An older db-backup build that still ran the job inside the request |
Update db-backup; see the deployment note in the companion page |
Testing each hop
Confirm the backup API directly, then through Laravel, then through the public route. That isolates which layer is broken.
# 1. db-backup, straight from the frontend container
docker exec ems-frontend sh -lc 'curl -sS http://db-backup:8096/api/v1/health'
# 2. the job status, as Laravel will read it
docker exec ems-frontend sh -lc 'curl -sS http://db-backup:8096/api/v1/job/status'
# 3. the same, as one line you can watch
docker exec ems-frontend sh -lc 'curl -sS "http://db-backup:8096/api/v1/job/status?format=text"'
# 4. through Laravel, with the bearer token and a u_key
docker exec ems-frontend sh -lc '
TOK=$(sed -n "s/^EMS_SETTINGS_API_TOKEN=//p" .env | head -1 | tr -d "\r\"")
curl -sS -H "Authorization: Bearer $TOK" \
"http://ems-nginx/api/v1/ems/backup-status?u_key=<user-u-key>"'
ems-frontend runs php-fpm with no HTTP listener, so shell tests must target
ems-nginx, as in step 4.
Gotchas
- Route cache. Add a route, then run
php artisan route:cache. Without it the route 404s despite existing on disk. u_keyis required on every route, even the read-only status poll. It is the app's own auth check, separate from the bearer token.- Keep the poll out of the audit log.
UserOperationService::log()on a 3 s poll will bury the table. - Do not raise the timeouts back. The trigger no longer needs to outlive the job, so 30 s is generous; the old 300/600 s values only existed to survive the blocking call, and on the restore path they hid the fact that the backup API was killing the job.
format=textis for humans and shell watches, not for the frontend. Parse the JSON.- A stalled dump shows up as
progress.file_age_secondsclimbing into the minutes whilerunningstays true. Worth surfacing, because the script logs nothing while it works.