feat(installer): install Device Agent without One-Time-Code #446

ppawlowski · 2025-07-06T11:07:08Z

Description

This pull request introduces a possibility to run the Device Agent Installer without the need to provide the One-Time-Code used for automatic device onboarding.
Without OTC provided:

a user is asked to confirm non-automatic Device Agent configuration
when the Device Agent configuration phase is reached, a user is asked to provide the device.yaml content or skip the configuration step
when the content of device.yaml is provided, simple validation is made, and the file is saved in the proper directory, installation continues
when configuration is skipped, the Device Agent is left unconfigured. User receives simple information of the manual steps needed to be done to complete the configuration process

Related Issue(s)

Closes #407

Checklist

I have read the contribution guidelines
Suitable unit/system level tests have been added and they pass
Documentation has been updated
- Upgrade instructions
- Configuration details
- Concepts
Changes flowforge.yml?
- Issue/PR raised on FlowFuse/helm to update ConfigMap Template
- Issue/PR raised on FlowFuse/CloudProject to update values for Staging/Production

Labels

Includes a DB migration? -> add the area:migration label

Steve-Mcl

In this current iteration, if a device.yml is found, the only option is to QUIT or DELETE and continue. I am not sure it works as Nick had expected.

Consider this set of steps:

User already has a device.yml in place (or restored it from a backup, or downloaded it from the FF device setup dialog)
User runs installer
Installer finds device.yml
The only option is to delete the file to continue.

IMO, just like if you installed Device Agent via NPM, it will simply start up and use device.yml already present.

I think the better approach is to (like NPM installation does today) is to keep existing yml (or at least offer the option to use existing yml file)

Output

One time code has not been provided. The Device Agent automatic configuration is not possible.
Do you want to continue with the installation? (y/N): y
Continuing with installation in interactive mode...
Logger initialized.
****************************************************************
*            FlowFuse Device Agent Installer                   *
*                                                              *
* This installer will set up the FlowFuse Device Agent on your *
* system and configure it to run as a system service.          *
*                                                              *
****************************************************************
Installing FlowFuse Device Agent...
The working directory c:\opt\flowfuse-device exists and contains Device Agent configuration file
Do you want to remove it and continue installation? (Y/n): n
[ERROR] Installation failed: pre-check failed: configuration file pre-check failed: the c:\opt\flowfuse-device directory has not been removed. Please remove it manually and try again

hardillb · 2025-07-10T08:42:48Z

Yep I agree with Steve, if there is an existing file it should offer the choice to use it.

…-no-otc-install

ppawlowski · 2025-07-10T21:20:41Z

Added the possibility to decide what should happen if device.yml is detected.

Steve-Mcl · 2025-07-15T08:45:59Z

Tested new "keep settings" option - this was the result:

device-agent\installer\go\out\windows>flowfuse-device-installer-windows-amd64.exe
One time code has not been provided. The Device Agent automatic configuration is not possible.
Do you want to continue with the installation? (y/N): y
Continuing with installation in interactive mode...
Logger initialized.
****************************************************************
*            FlowFuse Device Agent Installer                   *
*                                                              *
* This installer will set up the FlowFuse Device Agent on your *
* system and configure it to run as a system service.          *
*                                                              *
****************************************************************
Installing FlowFuse Device Agent...
The working directory c:\opt\flowfuse-device exists and contains Device Agent configuration file
Device Agent configuration already exists. What would you like to do?
* 1. Keep existing configuration and continue installation
  2. Remove all content and do fresh installation
  3. Cancel installation
Please select an option (1-3) [default: 1]:
Keeping existing configuration file, continuing with installation...
Checking Node.js installation...
Node.js version 20.19.1 found.
Installing FlowFuse Device Agent latest version...
FlowFuse Device Agent installed successfully!
Configuring FlowFuse Device Agent...
Device Agent is already configured, skipping configuration.
Configuring FlowFuse Device Agent to run as system service...
Installing FlowFuse Device Agent service for windows...
[ERROR] Service setup failed: failed to create service: exit status 5
 utput: E r r o r   c r e a t i n g   s e r v i c e !
 C r e a t e S e r v i c e ( ) :   T h e   s p e c i f i e d   s e r v i c e   a l r e a d y   e x i s t s .


[ERROR] Installation failed: service setup failed: failed to create service: exit status 5
 utput: E r r o r   c r e a t i n g   s e r v i c e !
 C r e a t e S e r v i c e ( ) :   T h e   s p e c i f i e d   s e r v i c e   a l r e a d y   e x i s t s .

Observations:

Looks like UTF-16 text is being parsed as UTF-8/ascii (might want to look into https://pkg.go.dev/golang.org/x/text/encoding/unicode)
Double output of error
First line One time code has not been provided. The Device Agent automatic configuration is not possible. is a bit confusing. I'm not even certain any of it is necessary TBH. We might as well just start the output at the ********** banner text
Should not output Logger initialized. (IMO)

Hard Issues:

If the service is already installed, this cannot continue without deleting config (i.e. to get past the service error I need to either a) run with --uninstall - this deletes config or b) run with option 2 "remove content": - again this deletes config!)

…-no-otc-install

ppawlowski · 2025-07-19T18:39:30Z

Hard Issues:

If the service is already installed, this cannot continue without deleting config (i.e. to get past the service error I need to either a) run with --uninstall - this deletes config or b) run with option 2 "remove content": - again this deletes config!)

Fixed.

Looks like UTF-16 text is being parsed as UTF-8/ascii (might want to look into https://pkg.go.dev/golang.org/x/text/encoding/unicode)

Addressed in a separate issue.

Double output of error

Should not output Logger initialized. (IMO)

Fixed.

First line One time code has not been provided. The Device Agent automatic configuration is not possible. is a bit confusing. I'm not even certain any of it is necessary TBH. We might as well just start the output at the ********** banner text

Why did it confuse you? I wanted a user to be 100% sure what would happen and to give them a chance to cancel the installation process.

joepavitt · 2025-08-13T16:58:28Z

@ppawlowski can you drop a status update on here please, 25 days and no updates.

ppawlowski · 2025-08-13T17:56:52Z

@Steve-Mcl can I ask for feedback on my last comment, please?

Steve-Mcl · 2025-08-15T13:50:32Z

5. First line One time code has not been provided. The Device Agent automatic configuration is not possible. is a bit confusing. I'm not even certain any of it is necessary TBH. We might as well just start the output at the ********** banner text

Why did it confuse you? I wanted a user to be 100% sure what would happen and to give them a chance to cancel the installation process.

I can't remember. Lets forget that for now.

Steve-Mcl · 2025-08-15T13:56:09Z

Latest testing.

Run latest installer without entering a OTC (skip entering device.yml)

This was successful and outputs instructions at the end.

One time code has not been provided. The Device Agent automatic configuration is not possible.
Do you want to continue with the installation? (y/N): y
Continuing with installation in interactive mode...
****************************************************************
*            FlowFuse Device Agent Installer                   *
*                                                              *
* This installer will set up the FlowFuse Device Agent on your *
* system and configure it to run as a system service.          *
*                                                              *
****************************************************************
Installing FlowFuse Device Agent...
Checking Node.js installation...
Installing Node.js 20.19.1...
Installing FlowFuse Device Agent latest version...
FlowFuse Device Agent installed successfully!
Configuring FlowFuse Device Agent...
No OTC (One-Time Code) provided. Automatic configuration is not possible.
You can either:
  1. Install the device agent only (you'll need to configure it manually later)
  2. Provide a device configuration file now
Do you want to provide a device agent configuration now? (Y/n): n
Configuration completed successfully!
Configuring FlowFuse Device Agent to run as system service...
Installing FlowFuse Device Agent service for windows...

FlowFuse Device Agent installation completed successfully!
The Device Agent has been installed but it is not configured.
To complete the setup:
 1. Create a device.yml configuration file in c:\opt\flowfuse-device directory
 2. Start the Device Agent service
For information on how to manage the FlowFuse Device Agent,
  please refer to the documentation at https://github.com/FlowFuse/device-agent/blob/main/installer/README.md

My only suggestion would be we provide a batch/shell script that fires up the graphical setup (node/flowforge-device-agent --ui --ui-user admin --ui-pass admin --ui-port 3000 --ui-host 127.0.0.1) so that it can be configured from the built in web-ui - but this can abe considered at a later time

Run latest installer without entering a OTC (entering device.yml when prompted)

A second run (without removing the prev existing installation) failed at the service check.
In simple terms, the installer should not quit/exit because it found the existing service. Instead, it should either rebuild the service or just start what it finds.

One time code has not been provided. The Device Agent automatic configuration is not possible.
Do you want to continue with the installation? (y/N): y
Continuing with installation in interactive mode...
****************************************************************
*            FlowFuse Device Agent Installer                   *
*                                                              *
* This installer will set up the FlowFuse Device Agent on your *
* system and configure it to run as a system service.          *
*                                                              *
****************************************************************
Installing FlowFuse Device Agent...
Checking Node.js installation...
Node.js version 20.19.1 found.
Installing FlowFuse Device Agent latest version...
FlowFuse Device Agent installed successfully!
Configuring FlowFuse Device Agent...
No OTC (One-Time Code) provided. Automatic configuration is not possible.
You can either:
  1. Install the device agent only (you'll need to configure it manually later)
  2. Provide a device configuration file now
Do you want to provide a device agent configuration now? (Y/n):
Please paste your device configuration below.
The configuration should be in YAML format with all required fields.
Enter an empty line when done:
deviceId: 7rg9ApE14a
token: ffd_Xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
credentialSecret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
forgeURL: http://192.168.xx.xx:3000
brokerURL: ws://172.xx.xx.183:8083
brokerUsername: device:d0bg4xgpR5:7rg9ApE14a
brokerPassword: ffbd_7k_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Device configuration saved successfully to: c:\opt\flowfuse-device\device.yml
Configuration completed successfully!
Configuring FlowFuse Device Agent to run as system service...
Installing FlowFuse Device Agent service for windows...
[ERROR] Service setup failed: failed to create service: exit status 5
Output: Error creating service!
CreateService(): The specified service already exists.

ppawlowski · 2025-08-18T09:17:32Z

A second run (without removing the prev existing installation) failed at the service check.

@Steve-Mcl Fixed, please re-review.

Steve-Mcl · 2025-08-18T09:22:40Z

A second run (without removing the prev existing installation) failed at the service check.

@Steve-Mcl Fixed, please re-review.

Yup, that'll do it 👍
I want to pull and test a few more scenarios (like the presence of a device.yml) and see if there are any scenarios where there is undesirable behaviour (like deletion of a perfectly good device.yml) or misleading text before I approve.

Please note: I am currently only checking against windows (would love to see some tests and trials by linux/mac users here in case I miss something)

ppawlowski · 2025-08-18T09:29:55Z

I want to pull and test a few more scenarios.

Could you share those testing scenarios afterwards? I will create a list of them for future use.

…-no-otc-install

Steve-Mcl

Windows all good

ppawlowski added 8 commits July 6, 2025 12:37

Add helper functions

8ad0f6d

Update helper functions in validate package

f1c7514

Do not start system service after its configuration

e946d1a

Handle empty OTC value in configuration steps

6197267

Update flags; add warning about empty OTC

cdcf171

Cleanup

90ab699

Update dependencies

08ff241

Update readme

388f494

ppawlowski requested review from Steve-Mcl and hardillb July 6, 2025 11:07

Steve-Mcl reviewed Jul 8, 2025

View reviewed changes

ppawlowski added 3 commits July 10, 2025 23:18

Introduce PromptOption function

fe6e673

Update checkConfigFileExists to handle existance of device.yml file

6515136

Merge branch 'main' of github.com:FlowFuse/device-agent into feat-dai…

d9f894c

…-no-otc-install

ppawlowski requested a review from Steve-Mcl July 10, 2025 21:20

ppawlowski added 2 commits July 17, 2025 13:12

Uninstall system service when keep config option is selected

5eb5c75

Silent successful logger initialization

ea629df

ppawlowski mentioned this pull request Jul 19, 2025

Installer: Error messages on Windows have bad formatting #457

Open

ppawlowski added this to 🛠 Development Jul 19, 2025

ppawlowski moved this to In Progress in 🛠 Development Jul 19, 2025

ppawlowski added 2 commits July 19, 2025 20:24

Do not print error message from main function

3d6f377

Merge branch 'main' of github.com:FlowFuse/device-agent into feat-dai…

43550ee

…-no-otc-install

joepavitt mentioned this pull request Aug 13, 2025

Installer: Support install without OTC #407

Closed

Uninstall system service before installing it

4b33278

Merge branch 'main' of github.com:FlowFuse/device-agent into feat-dai…

5f77772

…-no-otc-install

Steve-Mcl approved these changes Aug 23, 2025

View reviewed changes

hardillb approved these changes Aug 27, 2025

View reviewed changes

joepavitt mentioned this pull request Aug 28, 2025

feat(installer): Add possibility to install in custom directory #476

Merged

10 tasks

joepavitt moved this from In Progress to Review in 🛠 Development Aug 28, 2025

joepavitt merged commit ec2391f into main Aug 28, 2025
7 checks passed

joepavitt deleted the feat-dai-no-otc-install branch August 28, 2025 08:31

feat(installer): install Device Agent without One-Time-Code #446

feat(installer): install Device Agent without One-Time-Code #446

Uh oh!

Conversation

ppawlowski commented Jul 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Related Issue(s)

Checklist

Labels

Uh oh!

Steve-Mcl left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hardillb commented Jul 10, 2025

Uh oh!

ppawlowski commented Jul 10, 2025

Uh oh!

Steve-Mcl commented Jul 15, 2025

Uh oh!

ppawlowski commented Jul 19, 2025

Uh oh!

joepavitt commented Aug 13, 2025

Uh oh!

ppawlowski commented Aug 13, 2025

Uh oh!

Steve-Mcl commented Aug 15, 2025

Uh oh!

Steve-Mcl commented Aug 15, 2025

Run latest installer without entering a OTC (skip entering device.yml)

Run latest installer without entering a OTC (entering device.yml when prompted)

Uh oh!

ppawlowski commented Aug 18, 2025

Uh oh!

Steve-Mcl commented Aug 18, 2025

Uh oh!

ppawlowski commented Aug 18, 2025

Uh oh!

Steve-Mcl left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ppawlowski commented Jul 6, 2025 •

edited

Loading

Steve-Mcl left a comment •

edited

Loading