Skip to content

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_code or log_file in this response. It used to carry the finished run's output because it waited for the job. Read the output from GET /api/v1/job/log instead.

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:

  • progress is absent for a restore whose log has no database lines yet, and eta_* is null until at least two databases have started. Always reach for the keys defensively.
  • eta_seconds averages the databases already finished in this run. Database sizes are uneven — ems_db alone 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_key is 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=text is for humans and shell watches, not for the frontend. Parse the JSON.
  • A stalled dump shows up as progress.file_age_seconds climbing into the minutes while running stays true. Worth surfacing, because the script logs nothing while it works.