docs: update DeployStack documentation with configuration file and logo guidelines

docs/deploystack/application-logo-configuration.md

@@ -0,0 +1,58 @@
+---
+description: DeployStack logo configuration guide. Add a custom logo to your application with automatic WebP conversion, CDN delivery, and square format optimization.
+---
+
+# Application Logo Configuration
+
+Add a custom logo to make your application stand out in the DeployStack catalog. Your logo will be automatically optimized and served through our CDN for the best performance.
+
+## Adding Your Logo
+
+Configure your logo in `.deploystack/config.yml` - [DeployStack Configuration File Reference](/docs/deploystack/deploystack-config-file.md):
+
+```yaml
+application:
+  logo: "https://example.com/path/to/logo.png"
+```
+
+## Logo Requirements
+
+### Supported Formats
+
+- PNG (`.png`)
+- JPEG (`.jpg`, `.jpeg`)
+- WebP (`.webp`)
+
+### Size Guidelines
+
+- Maximum input: 2 MB.
+- Final output will be:
+  - Square format (1:1 aspect ratio)
+  - Maximum 500x500 pixels
+- Input images will be:
+  - Resized if larger than 500px in either dimension
+  - Centered and cropped to maintain 1:1 aspect ratio
+  - Padded with transparency if needed to achieve square format
+
+## Image Processing
+
+When you configure a logo, DeployStack automatically:
+
+1. Downloads your original image
+2. Optimizes it for web delivery
+3. Converts it to WebP format
+4. Stores it on our CDN
+5. Serves it through our global CDN network
+
+### Optimization Process
+
+- Images larger than 500px in either dimension are resized
+- Conversion to WebP for optimal compression
+- Automatic quality optimization for web delivery
+
+## Notes
+
+- The logo configuration is optional
+- You can update your logo at any time by modifying the config file
+- Logo changes are processed only when made on the default branch
+- Previous logo versions are automatically cleaned up

docs/deploystack/deploystack-config-file.md

@@ -0,0 +1,81 @@
+---
+description: Documentation for DeployStack's config.yml schema. Customize your application's presentation with automatic IDE validation and flexible repository metadata overrides.
+---
+
+# DeployStack Configuration File Reference
+
+The `.deploystack/config.yml` file allows you to customize how your application appears in the DeployStack catalog and deployment interfaces. This configuration file supports automatic validation in popular IDEs through SchemaStore integration.
+
+## Configuration File Location
+
+Create a `config.yml` file in your repository's `.deploystack` directory:
+
+```bash
+your-repository/
+├── .deploystack/
+│   ├── config.yml
+│   └── docker-compose.yml (example, or docker-run.txt)
+└── README.md
+```
+
+## Basic Configuration
+
+Here's a minimal configuration example:
+
+```yaml
+application:
+  name: "My Application"
+  description: "A scalable web application with Redis caching"
+  logo: "https://example.com/path/to/logo.png"
+```
+
+## Configuration Options
+
+### Application Settings
+
+When you submit a repository to DeployStack, we automatically use:
+
+- Repository name as the application name
+- Repository description as the application description
+
+You can override these values using the `config.yml` (only on your main branch) file:
+
+| Property | Type | Description | Constraints |
+|----------|------|-------------|-------------|
+| `name` | String | Override the repository name for DeployStack display | Maximum 40 characters |
+| `description` | String | Override the repository description for DeployStack display | Maximum 500 characters |
+| `logo` | String | URL to your application logo | [Application Logo Configuration](/docs/deploystack/application-logo-configuration.md) |
+
+The override process follows this order:
+
+1. DeployStack first uses your repository name and description
+2. If present, values in `.deploystack/config.yml` override the repository metadata
+
+## Schema Validation
+
+The configuration file is automatically validated against our JSON Schema when using supported IDEs (VS Code, IntelliJ, etc.). The schema is available at:
+
+```bash
+https://cdnx.deploystack.io/schema/config.yml.json
+```
+
+## Notes
+
+- Changes to the configuration file are only processed when made on your repository's default branch
+- The logo URL must be accessible and point to a valid image file
+- All configuration properties are optional, but providing them improves your application's visibility in the DeployStack catalog
+
+## Usage Examples
+
+### Override Repository Metadata
+
+```yaml
+application:
+  name: "Redis Cache Manager"      # Overrides repository name
+  description: "A more detailed description that better explains your application"  # Overrides repository description
+  logo: "https://example.com/logos/redis-manager.png"
+```
+
+### Minimal Configuration example for logo update
+
+Please visit our [Application Logo Configuration](/docs/deploystack/application-logo-configuration.md) page.

docs/deploystack/deploystack-configuration-directory.md

@@ -17,11 +17,14 @@ The `.deploystack` directory in your repository contains configuration files tha
 ├── docker-compose.yml  # Docker Compose configuration
 ├── docker-run.txt      # Docker run command
 ├── env                 # Environment variables (optional)
-└── logo.webp           # Project / app logo (optional)
 ```
 
 ## Configuration Files
 
+### DeployStack Configuration File
+
+Please read more at [DeployStack Configuration File Reference](/docs/deploystack/deploystack-config-file.md).
+
 ### Docker Configuration
 
 Choose one of the following:
@@ -48,28 +51,7 @@ docker run -d -p 80:80 nginx:alpine
 
 ### Environment Variables
 
-- File: `env` (optional)
-- Used with both Docker Compose and Docker run configurations
-- Contains key-value pairs for environment variables
-
-Example `env`:
-
-```bash
-DB_USER=admin
-DB_PASSWORD=secretpassword
-NGINX_PORT=80
-```
-
-### Repository Logo
-
-- Supported formats: `.png`, `.jpg`, `.jpeg`, `.webp`
-- Filename must be: `logo.<extension>`
-- Image will be minified to:
-  - Maximum width: 500px
-  - Maximum height: 500px
-- Automatically converted to WebP format for optimization
-
-Your logo will be stored on our CDN and converted to `webp` format. Please note that we will minimize your logo to max width 500px and max height 500px if it is larger than 500px w and 500px h.
+Please read more from our [environment variables](/docs/deploystack/docker-environment-variables.md) page.
 
 ## Automatic Updates
 
@@ -83,6 +65,6 @@ When the [DeployStack GitHub App](/docs/deploystack/github-application.md) is in
 
 - The `.deploystack` directory is **optional**
 - Without this directory, automatic template updates are **not** available
-- You can add the directory and install the GitHub App at any time
-- Environment variables and logo are optional components
+- You can add the directory and install the [DeployStack GitHub Sync App](/docs/deploystack/github-application.md) at any time
+- [Environment variables](/docs/deploystack/docker-environment-variables.md) and [DeployStack config](/docs/deploystack/deploystack-config-file.md) are optional components
 - Only one Docker configuration file should be used (either compose or run)

docs/deploystack/docker-compose-requirements.md

@@ -73,10 +73,7 @@ Currently, DeployStack only supports public images from Docker Hub. If you need
 
 ## Environment Variables
 
-A few notes about environment variables:
-
-- We support environment variables defined in your docker-compose.yml
-- Sensitive information should not be included in the docker-compose.yml
+Please read more from our [environment variables](/docs/deploystack/docker-environment-variables.md) page.
 
 ## Validation
 

docs/deploystack/docker-environment-variables.md

@@ -0,0 +1,111 @@
+---
+description: Learn how to manage environment variables in DeployStack using the .deploystack/env file. Support for Docker Compose, Docker run commands, and default values.
+---
+
+# Environment Variables in DeployStack
+
+DeployStack supports environment variables for your Docker configurations through the `.deploystack/env` file. This allows you to manage configuration values separately from your Docker files and maintain consistency across deployments.
+
+## Adding Environment Variables
+
+Create an `env` file in your `.deploystack` directory:
+
+```bash
+your-repository/
+├── .deploystack/
+│   ├── env
+└── README.md
+```
+
+Your `env` file should follow the standard environment file format:
+
+```bash
+# .deploystack/env
+DB_USERNAME=myuser
+DB_PASSWORD=mysecretpassword
+DB_DATABASE=mydatabase
+```
+
+## Using Environment Variables
+
+### In Docker Compose
+
+Reference environment variables in your `docker-compose.yml` using the `${VARIABLE_NAME}` syntax:
+
+```yaml
+services:
+  db:
+    image: mariadb:11.2
+    environment:
+      MYSQL_ROOT_PASSWORD: ${DB_PASSWORD}
+      MYSQL_USER: ${DB_USERNAME}
+      MYSQL_DATABASE: ${DB_DATABASE}
+```
+
+### In Docker Run Commands
+
+For `docker-run.txt`, use the same variable syntax:
+
+```bash
+docker run -d \
+  -e MYSQL_ROOT_PASSWORD=${DB_PASSWORD} \
+  -e MYSQL_USER=${DB_USERNAME} \
+  -e MYSQL_DATABASE=${DB_DATABASE} \
+  mariadb:11.2
+```
+
+## Default Values
+
+DeployStack supports Docker's default value syntax for environment variables. This provides fallback values when variables are not defined.
+
+### Syntax
+
+Use `${VARIABLE:-default}` where:
+
+- `VARIABLE` is your environment variable name
+- `default` is the fallback value
+
+### Examples
+
+```yaml
+# docker-compose.yml
+services:
+  web:
+    image: nginx:alpine
+    environment:
+      PORT: ${PORT:-8080}
+      NODE_ENV: ${NODE_ENV:-development}
+```
+
+```bash
+# docker-run.txt
+docker run -d \
+  -e PORT=${PORT:-8080} \
+  -e NODE_ENV=${NODE_ENV:-development} \
+  nginx:alpine
+```
+
+## Environment Variable Processing
+
+When DeployStack processes your repository:
+
+1. Variables defined in `.deploystack/env` are read
+2. These values replace matching `${VARIABLE}` placeholders
+3. For undefined variables:
+   - If a default value is specified (`${VARIABLE:-default}`), it's used
+   - Otherwise, an empty string is used
+
+## Important Notes
+
+- The `env` file is optional
+- Keep sensitive information out of version control
+- Variable names are case-sensitive
+- Default values provide fallbacks but don't expose sensitive data
+- Environment variables in your Docker configuration must use the `${VARIABLE}` syntax
+
+## Limitations
+
+- Basic environment variable substitution only
+- No variable expansion or shell-style manipulation
+- Cannot reference other variables within values
+- No built-in encryption for sensitive values

docs/sidebar-links.json

@@ -11,15 +11,23 @@
       {
         "text": "Configuration Directory",
         "link": "/docs/deploystack/deploystack-configuration-directory.md"
-      },      
+      },
+      {
+        "text": "Configuration File",
+        "link": "/docs/deploystack/deploystack-config-file.md"
+      },
+      {
+        "text": "Application Logo Configuration",
+        "link": "/docs/deploystack/application-logo-configuration.md"
+      },
       {
         "text": "IaC Lifecycle",
         "link": "/docs/deploystack/iac-lifecycle.md"
       },
       {
         "text": "GitHub Applicaton",
         "link": "/docs/deploystack/github-application.md"
-      },      
+      },
       {
         "text": "One Click Deploy",
         "link": "/docs/deploystack/one-click-deploy.md"
@@ -28,6 +36,10 @@
         "text": "Docker Compose Requirements",
         "link": "/docs/deploystack/docker-compose-requirements.md"
       },
+      {
+        "text": "Docker Environment Variables",
+        "link": "/docs/deploystack/docker-environment-variables.md"
+      },      
       {
         "text": "Troubleshooting",
         "link": "/docs/deploystack/troubleshooting.md"