docs: Add documentation for FlatRun Agent by Lantum-Brendan · Pull Request #152 · flatrun/agent

Lantum-Brendan · 2026-06-25T09:38:54Z

Add docs.json manifest and 5 markdown files covering overview, installation, configuration, API reference, and security.

sourceant · 2026-06-25T09:39:04Z

Code Review Summary

This PR adds comprehensive documentation for the FlatRun Agent, including installation guides, configuration references, and a full OpenAPI 3.2 specification.

🚀 Key Improvements

Added a systemd service unit following best practices for non-root execution.
Provided a full OpenAPI definition for all API endpoints.
Consolidated overview, security, and plugin architecture into dedicated files.

💡 Minor Suggestions

Improve parameter syntax consistency between API reference markdown and OpenAPI YAML.
Update example paths to align with the recommended production directory /opt/flatrun.

sourceant

Review complete. See the overview comment for a summary.

sourceant · 2026-06-25T09:39:05Z

+  enabled: true
+  api_keys:
+    - "your-secure-api-key-here"
+  jwt_secret: "generate-a-secure-random-string-here"


Hardcoding a specific instruction to generate a secret is better than using a placeholder string which might be accidentally left in production configurations.

Suggested change

jwt_secret: "generate-a-secure-random-string-here"

jwt_secret: "REPLACE_WITH_SECURE_RANDOM_STRING"

nfebe

Instead of manually documenting all endpoints... we could introduce the openapi standard

sourceant

Review complete. See the overview comment for a summary.

sourceant · 2026-06-29T18:51:47Z

+    { "title": "Installation", "path": "docs/installation.md" },
+    { "title": "Configuration", "path": "docs/configuration.md" },
+    { "title": "API Reference", "path": "docs/api-reference.md" },
+    { "title": "Plugin Architecture", "path": "docs/PLUGIN_ARCHITECTURE.md" },


Consistency: All other documentation files use kebab-case (e.g., api-reference.md). It is recommended to rename PLUGIN_ARCHITECTURE.md to plugin-architecture.md for consistency and better URL readability in some static site generators.

Suggested change

{ "title": "Plugin Architecture", "path": "docs/PLUGIN_ARCHITECTURE.md" },

{ "title": "Plugin Architecture", "path": "docs/plugin-architecture.md" },

sourceant · 2026-06-29T18:51:47Z

+
+[Service]
+Type=simple
+User=root


Security Best Practice: Running the agent as root is generally discouraged unless strictly necessary. Since the agent primarily needs access to the Docker socket, it is safer to create a dedicated system user and add them to the docker group.

Suggested change

User=root

User=flatrun

Group=docker

sourceant · 2026-06-29T18:51:47Z

+[Service]
+Type=simple
+User=root
+WorkingDirectory=/opt/flatrun


The installation guide should include a step to create the /opt/flatrun directory, otherwise the service will fail to start due to a missing WorkingDirectory.

Suggested change

WorkingDirectory=/opt/flatrun

WorkingDirectory=/opt/flatrun

# Ensure you run: sudo mkdir -p /opt/flatrun && sudo chown flatrun:flatrun /opt/flatrun

sourceant

Review complete. See the overview comment for a summary.

sourceant · 2026-06-29T18:53:39Z

+Type=simple
+User=root
+WorkingDirectory=/opt/flatrun
+ExecStart=/usr/local/bin/flatrun-agent --config /opt/flatrun/config.yml


The systemd service unit points to a config file in /opt/flatrun/config.yml, but the guide doesn't explicitly mention copying the config file to this directory. Users following this guide step-by-step will encounter a failure on startup.

Suggested change

ExecStart=/usr/local/bin/flatrun-agent --config /opt/flatrun/config.yml

ExecStart=/usr/local/bin/flatrun-agent --config /opt/flatrun/config.yml

# Note: Ensure you copy your config.yml to /opt/flatrun/ before starting.

…sistency

sourceant

Review complete. See the overview comment for a summary.

sourceant · 2026-06-29T19:04:03Z

@@ -0,0 +1,14057 @@
+openapi: 3.2.0


The OpenAPI version 3.2.0 is not yet a standard officially supported by most tooling (3.0.x and 3.1.0 are standard). Using 3.1.0 is recommended for better compatibility with Swagger UI/Redoc.

Suggested change

openapi: 3.2.0

openapi: 3.1.0

sourceant · 2026-06-29T19:04:04Z

+### Reference
+
+```yaml
+deployments_path: /home/user/deployments


The example path /home/user/deployments is a user-specific path. For a system-wide agent, it's better to suggest a path like /var/lib/flatrun/deployments to match standard Linux directory hierarchies.

Suggested change

deployments_path: /home/user/deployments

deployments_path: /var/lib/flatrun/deployments

sourceant

Review complete. See the overview comment for a summary.

sourceant · 2026-06-29T19:04:24Z

+
+nginx:
+  container_name: nginx
+  config_path: /deployments/nginx/conf.d


The configuration example uses /deployments/nginx/conf.d as a path, while the deployments_path at the top of the file suggests /home/user/deployments. This might confuse users about where the nginx configuration should reside relative to the deployments root.

Suggested change

config_path: /deployments/nginx/conf.d

config_path: /var/lib/flatrun/nginx/conf.d

sourceant · 2026-06-29T19:04:24Z

+```ini
+[Unit]
+Description=FlatRun Agent
+After=network.target docker.service


Adding After=docker.service is good, but for better robustness, BindsTo=docker.service or PartOf=docker.service ensures the agent stops if the Docker daemon crashes or is stopped, which is critical since the agent depends entirely on it.

Suggested change

After=network.target docker.service

After=network.target docker.service

BindsTo=docker.service

…opy steps

sourceant

Review complete. See the overview comment for a summary.

sourceant · 2026-06-29T19:09:03Z

+
+nginx:
+  container_name: nginx
+  config_path: /deployments/nginx/conf.d


Consistency issue: The config_path refers to /deployments/... but the global deployments_path (line 12) is defined as /home/user/deployments. Using relative paths or consistent absolute paths is recommended to prevent confusion.

Suggested change

config_path: /deployments/nginx/conf.d

config_path: /home/user/deployments/nginx/conf.d

sourceant · 2026-06-29T19:09:03Z

+[Unit]
+Description=FlatRun Agent
+After=network.target docker.service
+Requires=docker.service


Adding Requires=docker.service ensures the service fails if Docker isn't available, but BindsTo=docker.service is even stronger, ensuring that if Docker is stopped or restarted, the FlatRun Agent follows suit.

Suggested change

Requires=docker.service

Requires=docker.service

BindsTo=docker.service

sourceant · 2026-06-29T19:09:03Z

@@ -0,0 +1,23 @@
+## Security
+


The security section is currently a list of troubleshooting tips and basics. Consider adding a specific section about Docker socket security, as providing access to /var/run/docker.sock is equivalent to giving root access to the host.

Suggested change

## Security

- Use strong, unique API keys.

- Generate a secure JWT secret: `openssl rand -base64 32`.

- Run behind a reverse proxy (nginx) with HTTPS in production.

- **Restrict Docker socket access**: Ensure only the `docker` group and the `flatrun` user can access the socket. Avoid exposing the socket over TCP.

- Keep the agent updated.

sourceant

Review complete. No specific code suggestions were generated. See the overview comment for a summary.

sourceant

Review complete. See the overview comment for a summary.

sourceant · 2026-06-29T19:11:50Z

+  enabled: true
+  api_keys:
+    - "your-secure-api-key-here"
+  jwt_secret: "REPLACE_WITH_SECURE_RANDOM_STRING"  # generate via: openssl rand -base64 32


Security risk: While the comment suggests generating a secret, providing a placeholder in a documentation snippet often leads to users leaving it as-is. It is safer to use a prompt that clearly indicates action is required.

Suggested change

jwt_secret: "REPLACE_WITH_SECURE_RANDOM_STRING" # generate via: openssl rand -base64 32

+ jwt_secret: "GENERATED_VIA_OPENSSL_RAND" # generate via: openssl rand -base64 32

docs: Add documentation for flatrun-agent

14ff7c8

Add docs.json manifest and 5 markdown files covering overview, installation, configuration, API reference, and security.

sourceant Bot suggested changes Jun 25, 2026

View reviewed changes

nfebe requested changes Jun 26, 2026

View reviewed changes

docs: add OpenAPI 3.2 spec for FlatRun Agent

b366f72

sourceant Bot suggested changes Jun 29, 2026

View reviewed changes

docs: add OpenAPI spec reference to sidebar

291e902

sourceant Bot reviewed Jun 29, 2026

View reviewed changes

Lantum-Brendan added 2 commits June 29, 2026 20:03

docs(configuration): use explicit placeholder for jwt_secret

3b2454b

docs: rename PLUGIN_ARCHITECTURE.md to plugin-architecture.md for con…

f3d0460

…sistency

sourceant Bot reviewed Jun 29, 2026

View reviewed changes

docs(installation): use dedicated user, add dir creation and config c…

2a89c5b

…opy steps

sourceant Bot reviewed Jun 29, 2026

View reviewed changes

docs: remove old PLUGIN_ARCHITECTURE.md

9540c22

sourceant Bot approved these changes Jun 29, 2026

View reviewed changes

docs: add plugin-architecture.md (renamed from PLUGIN_ARCHITECTURE.md)

7529fc7

sourceant Bot suggested changes Jun 29, 2026

View reviewed changes

Lantum-Brendan requested a review from nfebe July 1, 2026 11:28

	jwt_secret: "generate-a-secure-random-string-here"
	jwt_secret: "REPLACE_WITH_SECURE_RANDOM_STRING"

	{ "title": "Plugin Architecture", "path": "docs/PLUGIN_ARCHITECTURE.md" },
	{ "title": "Plugin Architecture", "path": "docs/plugin-architecture.md" },

	WorkingDirectory=/opt/flatrun
	WorkingDirectory=/opt/flatrun
	# Ensure you run: sudo mkdir -p /opt/flatrun && sudo chown flatrun:flatrun /opt/flatrun

	ExecStart=/usr/local/bin/flatrun-agent --config /opt/flatrun/config.yml
	ExecStart=/usr/local/bin/flatrun-agent --config /opt/flatrun/config.yml
	# Note: Ensure you copy your config.yml to /opt/flatrun/ before starting.

	deployments_path: /home/user/deployments
	deployments_path: /var/lib/flatrun/deployments

	config_path: /deployments/nginx/conf.d
	config_path: /var/lib/flatrun/nginx/conf.d

	After=network.target docker.service
	After=network.target docker.service
	BindsTo=docker.service

	config_path: /deployments/nginx/conf.d
	config_path: /home/user/deployments/nginx/conf.d

	Requires=docker.service
	Requires=docker.service
	BindsTo=docker.service

+## Security
+- Use strong, unique API keys.
+- Generate a secure JWT secret: `openssl rand -base64 32`.
+- Run behind a reverse proxy (nginx) with HTTPS in production.
+- **Restrict Docker socket access**: Ensure only the `docker` group and the `flatrun` user can access the socket. Avoid exposing the socket over TCP.
+- Keep the agent updated.

	jwt_secret: "REPLACE_WITH_SECURE_RANDOM_STRING" # generate via: openssl rand -base64 32
	+ jwt_secret: "GENERATED_VIA_OPENSSL_RAND" # generate via: openssl rand -base64 32

Uh oh!

Conversation

Lantum-Brendan commented Jun 25, 2026

Uh oh!

sourceant Bot commented Jun 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Review Summary

🚀 Key Improvements

💡 Minor Suggestions

Uh oh!

sourceant Bot left a comment

Choose a reason for hiding this comment

Uh oh!

sourceant Bot Jun 25, 2026

Choose a reason for hiding this comment

Uh oh!

nfebe left a comment

Choose a reason for hiding this comment

Uh oh!

sourceant Bot left a comment

Choose a reason for hiding this comment

Uh oh!

sourceant Bot Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

sourceant Bot Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

sourceant Bot Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

sourceant Bot left a comment

Choose a reason for hiding this comment

Uh oh!

sourceant Bot Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

sourceant Bot left a comment

Choose a reason for hiding this comment

Uh oh!

sourceant Bot Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

sourceant Bot Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

sourceant Bot left a comment

Choose a reason for hiding this comment

Uh oh!

sourceant Bot Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

sourceant Bot Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

sourceant Bot left a comment

Choose a reason for hiding this comment

Uh oh!

sourceant Bot Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

sourceant Bot Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

sourceant Bot Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

sourceant Bot left a comment

Choose a reason for hiding this comment

Uh oh!

sourceant Bot left a comment

Choose a reason for hiding this comment

Uh oh!

sourceant Bot Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

sourceant Bot commented Jun 25, 2026 •

edited

Loading