frappe / frappe/pilot

Setup wizard cannot finish with systemd process manager due to Procfile check

Open
#458 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
101
Forks
61
Avg merge
2d 7h
Merged PRs (30d)
42

Description

## Bug Description

The Pilot setup wizard cannot complete when a bench is configured to use the **systemd** production process manager.

The setup itself completes successfully, the generated systemd services are valid and running, but the final setup API returns:

```json
{
"error": {
"code": "setup_not_initialized",
"details": {},
"message": "Bench setup has not finished."
}
}
```

The browser receives:

```text
POST /api/v1/setup/actions/finish
409 Conflict
```

## Root Cause

The setup finish endpoint currently determines whether the bench has been initialized by checking for:

```text
config/Procfile
```

Specifically:

```python
if not (bench_root / "config" / "Procfile").exists():
return error_response(
"setup_not_initialized",
"Bench setup has not finished.",
409,
)
```

This assumption is not valid for all process managers.

`SystemdProcessManager.write_config()` generates systemd units under:

```text
config/services/
```

For example:

```text
v15-admin.service
v15-admin.socket
v15-redis_cache.service
v15-redis_queue.service
v15-socketio.service
v15-web.service
v15-worker_pool.service
v15.target
```

It does **not** generate `config/Procfile`.

Therefore a successfully initialized production bench can be rejected by `/api/v1/setup/actions/finish`.

The same design should also be reviewed for the Supervisor process manager, since its configuration is not represented by a Procfile either.

## Reproduction

Environment:

```text
Pilot: v0.0.29-pre-alpha
Ubuntu
Production process manager: systemd
```

Bench configuration:

```toml
[production]
enabled = true
process_manager = "systemd"
```

Run the Pilot setup wizard normally.

The initialization task completes successfully, including:

```text
[12/12] Generate process config...
Bench initialised.
```

The generated systemd services are present and running:

```text
v15-admin.service
v15-redis_cache.service
v15-redis_queue.service
v15-socketio.service
v15-web.service
v15-worker_pool.service
```

`v15.target` is also active.

However:

```bash
test -f config/Procfile && echo EXISTS || echo MISSING
```

returns:

```text
MISSING
```

Clicking **Finish** in the setup wizard then repeatedly results in:

```text
POST /api/v1/setup/actions/finish
409 Conflict
```

with:

```json
{
"error": {
"code": "setup_not_initialized",
"message": "Bench setup has not finished.",
"details": {}
}
}
```

## Confirmed Workaround

Creating an empty Procfile:

```bash
touch config/Procfile
```

immediately allows the setup wizard to finish successfully.

No other configuration or service changes are required.

This confirms that the Procfile existence check is the blocker rather than an incomplete bench initialization.

## Expected Behaviour

The setup completion check should use a process-manager-independent indication that the bench has actually been initialized.

Pilot already uses the existence of the bench Python environment as its initialization test in `BenchRuntime._is_initialized()`:

```python
return self.bench.python.exists()
```

The setup API should preferably use the same initialization invariant rather than treating the presence of a Procfile as proof that initialization completed.

For example, the finish validation could check the bench Python executable:

```text
env/bin/python
```

instead of:

```text
config/Procfile
```

Alternatively, Pilot could expose a common bench initialization predicate and use it consistently throughout the runtime and setup APIs.

## Additional Concern

There appears to be a related inconsistency in process-manager configuration detection.

The local process manager implements:

```python
def is_configured(self) -> bool:
return self.procfile_path.exists()
```

Systemd and Supervisor provide their own `write_config()` implementations and generate process-manager-specific configuration, but configuration detection should not depend on a Procfile that those managers do not generate.

It may therefore be worth reviewing the process-manager-specific `is_configured()` behaviour separately from the setup wizard fix.

## Suggested Fix

For the immediate setup wizard issue:

1. Remove the hard-coded `config/Procfile` requirement from `/api/v1/setup/actions/finish`.
2. Use the same process-manager-independent bench initialization condition used by the runtime.
3. Add a regression test where:

* the `wizard-setup` task completes successfully;
* `env/bin/python` exists;
* no `config/Procfile` exists;
* `/api/v1/setup/actions/finish` returns `204`;
* `.wizard-active` is removed.
4. Preserve the existing `409 setup_not_initialized` behaviour when the actual bench initialization artifact is absent.

## Impact

This blocks completion of the web-based Pilot setup even though the production bench has been successfully initialized and its systemd services are operational.

The workaround of manually creating an empty Procfile is misleading because the file is not actually used by the systemd-managed bench.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start at the /api/v1/setup/actions/finish handler and compare its Procfile check with BenchRuntime._is_initialized(), then review process-manager is_configured() behavior. Add the regression coverage described for a completed wizard-setup task with env/bin/python present and no config/Procfile. Done means the endpoint returns 204, removes .wizard-active, and still returns 409 when the initialization artifact is absent.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
api, backend, devops
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
78/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.