Add a CLI warning when running launcher bootstrap/rebuild without app.yml present

Contribute Feature

AI-generated summary

The discussion proposes adding a clearer CLI warning when running launcher bootstrap or launcher rebuild without an app.yml file present. Currently, users encounter a vague error: ERROR: containers/app.yml does not exist or is not readable. This often confuses new users who may have skipped ./discourse-setup or are restoring a Discourse instance. Ethsim2 suggests enhancing the error message to guide users based on their scenario: first-time installers should run ./discourse-setup (which generates app.yml from standalone.yml), those restoring a server should ensure app.yml is copied, and testers avoiding email setup can proceed with a local instance. The proposed warning would be more helpful and reduce confusion for all user types. Ethsim2 further refines the message to cover these cases explicitly, improving the user experience for both new and experienced admins.

1

When a fresh clone of Discourse is set up, the repository ships with standalone.yml.

The documented workflow is:

git clone https://github.com/discourse/discourse_docker.git /var/discourse
cd /var/discourse
./discourse-setup   # creates app.yml

But if someone skips ./discourse-setup and instead runs

./launcher bootstrap app
# or
./launcher rebuild app

while app.yml does not exist, they get a confusing error because app.yml is not present, and standalone.yml is not automatically recognized as a starting point.

This is a common stumbling block for new admins who assume standalone.yml is already valid for use.

Proposal:

  • When launcher bootstrap or launcher rebuild is called and containers/app.yml does not exist, the CLI should print a clear warning like:
No containers/app.yml found.
Did you mean to run ./discourse-setup first?
Note: app.yml is generated from the sample standalone.yml file.

This would save new users from running into a dead end and searching Meta for answers.

Would this be a reasonable addition to launcher?

2 Likes
2

Yes, at the moment if you run

./launcher bootstrap app

without first creating app.yml, you only see:

ERROR: containers/app.yml does not exist or is not readable.

That’s accurate but not very helpful, especially for two common cases:

  1. New production install
    Should run ./discourse-setup to generate app.yml from standalone.yml.

  2. Quick test forum without outbound email
    Sometimes people just want to spin up a local/test Discourse without configuring SMTP.
    The usual workflow is:

./launcher bootstrap app
./launcher start app
./launcher enter app
rake admin:create

This gives you an admin account without needing email.

Proposal:
Improve the error message so it guides both paths. For example:

1 Like
3

I’d just add that the official backup/restore guide encourages copying app.yml into place on a new VPS before running launcher.

So the error message could maybe cover that scenario as well. Right now, someone following the guide but forgetting to copy app.yml first will hit the same dead end.

Perhaps something like:

ERROR: containers/app.yml does not exist or is not readable.

If this is your first install, run ./discourse-setup to generate app.yml
(from the sample standalone.yml).

If you are restoring to a new server, make sure you copied your existing
app.yml from the old server into /var/discourse/containers

That way the message points all three kinds of users in the right direction:

  • brand-new admins
  • people restoring a forum
  • testers who don’t want to set up SMTP.