more config

Author: LineIndent

docs/hosting/config_file.md

@@ -4,8 +4,8 @@ from reflex_image_zoom import image_zoom
 from pcweb.pages.docs import hosting
 from pcweb.pages import docs
 from pcweb.styles.styles import get_code_style, cell_style
-
 ```
+
 ## What is reflex cloud config?
 
 The following command:
@@ -16,106 +16,252 @@ reflex cloud config
 
 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
+project: my-client-project          # Optional: for organization
+
+# Infrastructure settings
+regions:                            # Optional: defaults to sjc: 1
+  sjc: 1                           # San Jose (primary)
+  lhr: 2                           # London (secondary)
+vmtype: c2m2                       # Optional: defaults to c1m1
+
+# Custom domain and environment
+hostname: myapp.com                 # Optional: null uses default Reflex URL
+envfile: .env.production           # Optional: defaults to .env
+
+# Additional dependencies
+packages:                          # Optional: empty by default
+  - procps
+  - imagemagick
+```
+
+## 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", "Human-readable deployment description", 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 domain configuration", "/docs/hosting/custom-domains"),
+            ("envfile", "string", ".env", "Environment variables file path", "/docs/hosting/secrets-environment-vars"),
+            ("project", "string", "null", "Project organization", None),
+            ("packages", "array", "empty", "Additional system packages", None),
+        ]
+    ]),
+    variant="ghost",
+    size="2",
+    width="100%",
+    max_width="800px",
+)
+```
 
-## What does cloud.yml contain?
+## Detailed Configuration Options
 
-Here is an example cloud.yml file generated by the command:
+### Regions
+
+Available deployment regions with their codes:
+
+- `sjc`: San Jose, California (US West)
+- `lhr`: London, United Kingdom (Europe)
+- `fra`: Frankfurt, Germany (Europe)
+- `syd`: Sydney, Australia (Asia-Pacific)
+
+Specify regions using the format `region: instance_count`:
 
 ```yaml
-name: default
-description: ''
 regions:
-  sjc: 1
-  lhr: 2
-vmtype: c1m1
-hostname: null
-envfile: .env
-project: null
-packages:
-- procps
+  sjc: 1    # Primary region with 1 instance
+  lhr: 2    # Backup region with 2 instances for high availability
 ```
 
-### Configuration Options Explained
+**Use Cases:**
+- Single region: Cost-effective for regional applications
+- Multi-region: Global applications requiring low latency and redundancy
 
-**name**
-- Identifies your deployment in the Reflex Cloud dashboard
-- Use descriptive names like `myapp-prod` or `myapp-staging`
+### VM Types
 
-**description**
-- Optional but helpful for team collaboration
-- Document what this deployment is for
+Choose the appropriate virtual machine size based on your application needs:
 
-**regions**
-- Available regions: `sjc` (San Jose), `lhr` (London), `fra` (Frankfurt), `syd` (Sydney)
-- Format: `region: instance_count`
-- Use multiple regions for global availability and redundancy
+### Custom Domains
 
-**vmtype**
-- `c1m1`: 1 CPU, 1GB RAM (development/small apps)
-- `c2m2`: 2 CPU, 2GB RAM (production ready)
-- `c4m4`: 4 CPU, 4GB RAM (high traffic apps)
-- `c8m8`: 8 CPU, 8GB RAM (enterprise apps)
+Set `hostname` to use your own domain instead of the default Reflex Cloud URL:
 
-**hostname**
-- Leave as `null` for default Reflex Cloud URL
-- Set custom domain if you own one
-- Requires DNS configuration (see Custom Domains section)
+```yaml
+hostname: myapp.com
+```
 
-**envfile**
-- Path to your environment variables file
-- Default is `.env` in your project root
-- Never commit this file to version control
+**Requirements:**
+- Domain ownership verification
+- DNS configuration (CNAME or A record)
+- SSL certificate (handled automatically)
 
-**project**
-- Optional: organizes deployments within your account
-- Useful for separating client projects or environments
+### Environment Variables
 
-**packages**
-- Additional packages your app needs
+Specify the path to your environment variables file:
 
-### Environment Variables (Optional)
+```yaml
+envfile: .env.production  # Custom environment file
+```
 
-If your app uses environment variables, create a `.env` file in your project root:
+Example `.env` file structure:
 
 ```bash
-# Database
+
 DATABASE_URL=postgresql://user:pass@host:port/dbname
 
-# API Keys
 OPENAI_API_KEY=your_api_key_here
 STRIPE_SECRET_KEY=sk_live_...
 
-# App Configuration
 DEBUG=False
 SECRET_KEY=your_secret_key_here
+```
+
+### Projects
+
+Organize deployments using projects:
+
+```yaml
+project: client-alpha    # Groups related deployments
+```
+
+Projects help separate:
+- Different clients or customers
+- Development, staging, and production environments
+- Team-based application ownership
+
+### Packages
+
+Install additional system packages your application requires:
 
-# Custom Variables
-CUSTOM_API_ENDPOINT=https://api.example.com
+```yaml
+packages:
+  - procps      # Process monitoring tools
+  - imagemagick # Image processing
+  - ffmpeg      # Media processing
+```
+
+## Multiple Configuration Examples
+
+### Minimal Configuration
+```yaml
+# Uses all defaults - suitable for development
+name: my-app-dev
+```
+
+### Production Configuration
+```yaml
+name: myapp-production
+description: 'Main production deployment'
+regions:
+  sjc: 2
+  lhr: 1
+vmtype: c4m4
+hostname: myapp.com
+envfile: .env.production
+project: myapp
+packages:
+  - imagemagick
+  - redis-tools
+```
+
+### Multi-Environment Setup
+
+**Development (`cloud-dev.yml`):**
+```yaml
+name: myapp-dev
+description: 'Development environment'
+vmtype: c1m1
+envfile: .env.development
 ```
 
-**Security Best Practices:**
-- Never commit `.env` to version control
-- Use different `.env` files for staging/production
-- Rotate secrets regularly
-- Use strong, unique values for SECRET_KEY
+**Staging (`cloud-staging.yml`):**
+```yaml
+name: myapp-staging
+description: 'Staging environment'
+regions:
+  sjc: 1
+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.com
+envfile: .env.production
+```
+
+## Using Different Configuration Files
+
+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
+```
+
+## Deployment Workflow
+
+1. **Generate base configuration:**
+   ```bash
+   reflex cloud config
+   ```
 
-## How to use the cloud.yml
+2. **Customize the `cloud.yml` file** based on your requirements using the options above
 
-1. Run reflex cloud config to generate the default `cloud.yml` file.
-2. Open `cloud.yml` and customize the keys to fit your app and deployment preferences.
-3. Ensure your .env file (or specified envfile) contains the necessary environment variables for your app.
-4. Deploy your app using Reflex cloud commands (e.g., reflex deploy).
+3. **Create environment file** (if needed):
+   ```bash
+   touch .env
+   # Add your environment variables
+   ```
 
-## Where to find values for keys?
+4. **Deploy your application:**
+   ```bash
+   reflex deploy
+   ```
 
-- `regions`: Check Reflex cloud documentation or dashboard for region codes and availability.
-- `vmtype`: Check Reflex cloud VM size options to pick the right balance of CPU/memory.
-- `hostname`: Use your own domain name if you want a custom URL, or leave as null for default URLs.
-- `project`: Your Reflex cloud account projects — find them on the Reflex dashboard.
-- `packages`: Add any extra packages your app requires to run.
+5. **Monitor deployment** through the (Reflex Cloud)[https://cloud.reflex.dev/] dashboard
 
 ## Summary
 
-Reflex Cloud provides a streamlined deployment experience for Python web applications. The `cloud.yml` configuration file gives you control over your deployment while maintaining simplicity. Start with basic configurations and scale up as your application grows.
+The `cloud.yml` configuration provides complete control over your Reflex Cloud deployments while maintaining simplicity. All configuration options are optional, allowing you to start with minimal setup and gradually add complexity as your application scales.
 
-For production applications, consider implementing proper monitoring, backup strategies, and CI/CD pipelines to ensure reliable deployments.
+Key takeaways:
+- Start with basic configuration and expand as needed
+- Use multiple configuration files for different environments
+- Leverage regions for global availability and redundancy
+- Secure environment variables and never commit them to version control

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,