[ENG-5990] fill out config.yaml docs (#1390)

* fill out config.yaml docs

* more config

* update

* uv lock

---------

Co-authored-by: Alek99 <[email protected]>
Co-authored-by: Alek Petuskey <[email protected]>

Author: 3 people

docs/hosting/config_file.md

@@ -1,32 +1,180 @@
 ```python exec
 import reflex as rx
 from reflex_image_zoom import image_zoom
-from pcweb.pages.docs import hosting 
+from pcweb.pages.docs import hosting
 from pcweb.pages import docs
 from pcweb.styles.styles import get_code_style, cell_style
-
 ```
-## Config File
 
-To create a `config.yml` file for your app run the command below:
+## What is reflex cloud config?
+
+The following command:
 
 ```bash
 reflex cloud config
 ```
 
-This will create a yaml file similar to the one below where you can edit the app configuration:
+generates a `cloud.yml` configuration file used to deploy your Reflex app to the Reflex cloud platform. This file tells Reflex how and where to run your app in the cloud.
+
+## Configuration File Structure
+
+The `cloud.yml` file uses YAML format and supports the following structure. **All fields are optional** and will use sensible defaults if not specified:
+
+```yaml
+# Basic deployment settings
+name: my-app-prod                    # Optional: defaults to project folder name
+description: 'Production deployment' # Optional: empty by default
+projectname: my-client-project          # Optional: defaults to personal project
+
+# Infrastructure settings
+regions:                            # Optional: defaults to sjc: 1
+  sjc: 1                           # San Jose (# of machines)
+  lhr: 2                           # London (# of machines)
+vmtype: c2m2                       # Optional: defaults to c1m1
+
+# Custom domain and environment
+hostname: myapp                    # Optional: myapp.reflex.dev
+envfile: .env.production           # Optional: defaults to .env
+
+# Additional dependencies
+packages:                          # Optional: empty by default
+  - procps
+```
+
+## Configuration Options Reference
+
+```python demo-only
+rx.table.root(
+    rx.table.header(
+        rx.table.row(
+            rx.table.column_header_cell(rx.text("Option", size="1", weight="bold", color=rx.color("slate", 11))),
+            rx.table.column_header_cell(rx.text("Type", size="1", weight="bold", color=rx.color("slate", 11))),
+            rx.table.column_header_cell(rx.text("Default", size="1", weight="bold", color=rx.color("slate", 11))),
+            rx.table.column_header_cell(rx.text("Description", size="1", weight="bold", color=rx.color("slate", 11))),
+            align="center"
+        )
+    ),
+    rx.table.body(*[
+        rx.table.row(
+            rx.table.cell(rx.text(option, class_name="text-sm")),
+            rx.table.cell(rx.text(type_, class_name="text-sm")),
+            rx.table.cell(rx.text(default, class_name="text-sm")),
+            rx.table.cell(rx.link(description, href=link, class_name="text-sm") if link else rx.text(description, size="1", weight="regular")),
+            align="center"
+        ) for option, type_, default, description, link in [
+            ("name", "string", "folder name", "Deployment identifier in dashboard", None),
+            ("description", "string", "empty", "Description of deployment", None),
+            ("regions", "object", "sjc: 1", "Region deployment mapping", "/docs/hosting/regions"),
+            ("vmtype", "string", "c1m1", "Virtual machine specifications", "/docs/hosting/machine-types"),
+            ("hostname", "string", "null", "Custom subdomain", None),
+            ("envfile", "string", ".env", "Environment variables file path", "/docs/hosting/secrets-environment-vars"),
+            ("project", "uuid", "null", "Project uuid", None),
+            ("projectname", "string", "null", "Project name", None),
+            ("packages", "array", "empty", "Additional system packages", None),
+            ("include_db", "boolean", "false", "Include local sqlite", None),
+            ("strategy", "string", "auto", "Deployment strategy", None)
+        ]
+    ]),
+    variant="ghost",
+    size="2",
+    width="100%",
+    max_width="800px",
+)
+```
+
+## Configuration Options
+
+For details of specific sections click the links in the table.
+
+### Projects
+
+Organize deployments using projects:
+
+```yaml
+projectname: client-alpha    # Groups related deployments
+```
+
+You can also specify a project uuid instead of name:
+```yaml
+project: 12345678-1234-1234-1234-1234567890ab
+```
+
+You can go to the homepage of the project in the reflex cloud dashboard to find your project uuid in the url `https://cloud.reflex.dev/project/uuid`
+
+### Apt Packages
+
+Install additional system packages your application requires. Package names are based on the apt package manager:
+
+```yaml
+packages:
+  - procps=2.0.32-1  # Version pinning is optional
+  - imagemagick 
+  - ffmpeg      
+```
+
+### Include SQLite
+
+Include local sqlite database:
+
+```yaml
+include_db: true
+```
+
+This is not persistent and will be lost on restart. It is recommended to use a database service instead.
+
+### Strategy
+
+Deployment strategy:
+Available strategies:
+- `immediate`: [Default] Deploy immediately
+- `rolling`: Deploy in a rolling manner
+- `bluegreen`: Deploy in a blue-green manner
+- `canary`: Deploy in a canary manner, boot as single machine verify its health and then restart the rest.
+
+```yaml
+strategy: immediate
+```
+
+## Multi-Environment Setup
 
+**Development (`cloud-dev.yml`):**
 ```yaml
-name: medo
-description: ''
+name: myapp-dev
+description: 'Development environment'
+vmtype: c1m1
+envfile: .env.development
+```
+
+**Staging (`cloud-staging.yml`):**
+```yaml
+name: myapp-staging
+description: 'Staging environment'
 regions:
   sjc: 1
-  lhr: 2
-vmtype: c1m1
-hostname: null
-envfile: .env
-project: null
-packages:
-- procps
+vmtype: c2m2
+envfile: .env.staging
+```
+
+**Production (`cloud-prod.yml`):**
+```yaml
+name: myapp-production
+description: 'Production environment'
+regions:
+  sjc: 2
+  lhr: 1
+vmtype: c4m4
+hostname: myapp
+envfile: .env.production
 ```
 
+Deploy with specific configuration files:
+
+```bash
+# Use default cloud.yml
+reflex deploy
+
+# Use specific configuration file
+reflex deploy --config cloud-prod.yml
+reflex deploy --config cloud-staging.yml
+```error: The lockfile at `uv.lock` needs to be updated, but `--locked` was provided. To update the lockfile, run `uv lock`.
+

pcweb/flexdown.py

@@ -279,6 +279,54 @@ def render(self, env) -> rx.Component:
             ),
         )
 
+class DemoOnly(flexdown.blocks.Block):
+    """A block that displays only a component demo without showing the code."""
+
+    starting_indicator = "```python demo-only"
+    ending_indicator = "```"
+    include_indicators = True
+    theme: str = None
+
+    def render(self, env) -> rx.Component:
+        lines = self.get_lines(env)
+        code = "\n".join(lines[1:-1])
+
+        args = lines[0].removeprefix(self.starting_indicator).split()
+
+        exec_mode = env.get("__exec", False)
+        comp = ""
+
+        for arg in args:
+            if arg.startswith("id="):
+                comp_id = arg.rsplit("id=")[-1]
+                break
+        else:
+            comp_id = None
+
+        if "exec" in args:
+            env["__xd"].exec(code, env, self.filename)
+            if not exec_mode:
+                comp = env[list(env.keys())[-1]]()
+        elif "graphing" in args:
+            env["__xd"].exec(code, env, self.filename)
+            if not exec_mode:
+                comp = env[list(env.keys())[-1]]()
+                # Get all the code before the final "def".
+                parts = code.rpartition("def")
+                data, code = parts[0], parts[1] + parts[2]
+                comp = docgraphing(code, comp=comp, data=data)
+                return comp
+        elif exec_mode:
+            return comp
+        elif "box" in args:
+            comp = eval(code, env, env)
+            return rx.box(comp, margin_bottom="1em", id=comp_id)
+        else:
+            comp = eval(code, env, env)
+
+        # Return only the component without any code display
+        return rx.box(comp, margin_bottom="1em", id=comp_id)
+
 
 class DemoBlock(flexdown.blocks.Block):
     """A block that displays a component along with its code."""
@@ -543,6 +591,7 @@ def render(self, env) -> rx.Component:
 
 xd = flexdown.Flexdown(
     block_types=[
+        DemoOnly,
         DemoBlock,
         AlertBlock,
         DefinitionBlock,